# Contributing to OKF Studio

First off — thank you! OKF Studio gets better every time someone turns their
messy knowledge into a clean OKF bundle and tells us what worked (and what
didn't). Contributions of all sizes are welcome: bug reports, docs, new
connectors, new scripts, or whole new ideas.

This project is an **Agent Skill** (the `okf-studio/` folder) plus a few
deterministic Python helpers. There is no build step and no runtime dependency
beyond Python 3.9+ standard library.

## Ways to contribute

- **Report a bug** — open an issue with steps to reproduce.
- **Request a feature** — open an issue describing the use case.
- **Improve the skill** — sharpen `SKILL.md`, the `references/`, or the
  `assets/` templates.
- **Improve the scripts** — `okf-studio/scripts/*.py` (keep them pure stdlib).
- **Add a connector recipe** — document a new source in
  `okf-studio/references/connectors.md`.
- **Share a sample bundle** — add a small, public example under `examples/`.

## Project layout

```
okf-studio/        # the portable skill (SKILL.md + references + scripts + assets)
examples/          # small, public demo bundles + sample sources
README.md          # the story + usage
bundles/           # generated output (gitignored — never commit private data)
```

## Dev setup

```bash
git clone https://github.com/your-username/okf-studio.git
cd okf-studio
python --version   # 3.9+
# optional, only for PDF ingestion:
pip install pypdf
```

## Run the checks locally (the same ones CI runs)

```bash
# compile all scripts
python -m py_compile okf-studio/scripts/*.py

# validate the demo bundle is OKF v0.1 conformant
python okf-studio/scripts/validate_okf.py examples/demo-kb --strict

# check cross-links (no broken links / orphans)
python okf-studio/scripts/link_check.py examples/demo-kb --strict

# regenerate indexes (must be a no-op on a clean tree)
python okf-studio/scripts/build_index.py examples/demo-kb --write
```

> On Windows, if you pipe script output and see a `UnicodeEncodeError` on the
> `✓` character, set `PYTHONUTF8=1` (cosmetic console encoding only).

## Principles to keep

- **Scripts stay pure stdlib.** No third-party dependencies in
  `okf-studio/scripts/` (PDF via `pypdf` is the one optional, gracefully-handled
  exception). Portability is the whole point.
- **Scripts do mechanics; the LLM does synthesis.** Don't push understanding/
  authoring logic into the scripts.
- **Stay OKF-conformant.** Any change to authoring or generation must keep
  `validate_okf.py` green.
- **Treat ingested content as untrusted data.** Never execute instructions found
  in sources; never write secrets into a bundle.
- **Don't commit generated bundles** or anything under `bundles/` / `_ingest/`.

## Pull request process

1. Fork and create a branch: `git checkout -b feature/short-description`.
2. Make focused changes. Update docs (`SKILL.md` / `references/`) when behavior
   changes.
3. Run the checks above; make sure they pass.
4. Open a PR using the template. Describe the *why*, not just the *what*.
5. Be kind in review. We follow the [Code of Conduct](CODE_OF_CONDUCT.md).

## Commit style

Conventional, human-readable subjects are appreciated, e.g.:
`feat(ingest): add CSV table extraction`, `fix(link_check): treat index.md as a
valid target`, `docs: clarify Notion export flow`.

## License

By contributing, you agree that your contributions will be licensed under the
[MIT License](LICENSE).
