# Maintainer Contract

This file defines the allowed structure, read scope, and CRUD rules for maintaining the onboarding kit. Follow it when adding, changing, disabling, inspecting, or repackaging the kit.

Python command compatibility: scripts require Python 3.10+. Documentation examples use `python3` for macOS/Linux; on Windows, if `python3` is unavailable, use `python` or `py -3` with the same arguments. Scripts that invoke other Python scripts should use `sys.executable` instead of hard-coding `python3`. Before answering or running scripts, detect Python first. If Python 3.10+ is unavailable, ask the user before using `bootstrap.ps1` on Windows or `sh bootstrap.sh` on macOS/Linux to install uv and run uv-managed Python. Use `search/chunks.jsonl` and cited files as a Q&A fallback only when the user declines installation or setup is blocked.

## Architecture

```text
AGENTS.md                         Global operating contract
AGENT_COMPATIBILITY.md            Cross-agent compatibility map
BOOTSTRAP.md                      First-run package bootstrap prompt
CLAUDE.md                         Claude Code adapter
GEMINI.md                         Gemini adapter
HANDOFF.md                        Maintainer and future-agent orientation
MAINTAINERS.md                    Maintenance and CRUD contract
.github/copilot-instructions.md   GitHub Copilot adapter
.cursor/rules/onboarding-kit.mdc  Cursor adapter
.clinerules                       Cline adapter
.ai/context/                      Six-layer durable context, state, evals, systemization
kit.yaml                          Kit metadata, owners, journeys, module order, search paths
start.prompt.md                   Learner-facing startup prompt
skills/onboarding-buddy/SKILL.md  Codex skill entrypoint and read order
modules/<module-id>/              One pluggable onboarding module
  module.yaml                     Module metadata and ownership
  steps.yaml                      Step-by-step executable flow
  knowledge.md                    Explanatory module knowledge
  faq.yaml                        Module FAQ and question patterns
sources/                          Source evidence and searchable extracted text
assets/                           Downloaded binary originals
search/                           Generated full-text index
state-template/                   Runtime state schema
scripts/                          Validation, ingestion, indexing, search, install, and module tools
```

## Authority Order

1. `AGENTS.md`: highest local operating contract.
2. `HANDOFF.md`: orientation for future maintainers and Codex handoff.
3. `MAINTAINERS.md`: maintenance and CRUD contract.
4. `.ai/context/`: durable six-layer context for intent, rules, workspace, state, evals, and systemization.
5. `kit.yaml`: enabled journeys, module order, owner keys, search paths.
6. `skills/onboarding-buddy/SKILL.md`: skill read order and execution flow.
7. `modules/<module-id>/module.yaml`: module ownership, prerequisites, metadata.
8. `modules/<module-id>/steps.yaml`: executable learner flow.
9. `knowledge.md`, `faq.yaml`, and `sources/`: answer evidence only.
10. `search/`: generated index only; never hand-edit.

If files conflict, prefer the higher-authority file. If business facts conflict, prefer the current module, then enabled modules, then the newest manifest-backed source.

## Query Read Scope

For first-run package bootstrap in a new agent session:

1. Read `AGENTS.md`.
2. Read `HANDOFF.md`.
3. Read `MAINTAINERS.md`.
4. Read `BOOTSTRAP.md`.
5. Detect Python: macOS/Linux `python3 --version`; Windows `py -3 --version` or `python --version`.
6. If Python 3.10+ is available, run `python3 scripts/validate_kit.py`, `python3 scripts/index_knowledge.py`, and `python3 scripts/bootstrap_session.py`.
7. If Python 3.10+ is unavailable and maintenance is required, ask the user before running `bootstrap.ps1` or `sh bootstrap.sh` to install uv and run the scripts with uv-managed Python.
8. Read `.ai/context/session-bootstrap.md`.
9. For the rest of the same agent session, answer questions through `scripts/search_knowledge.py` and cited files instead of rescanning the full package.

For agent adapter maintenance:

1. Keep adapter files thin.
2. Do not duplicate business process details into `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursor/rules/onboarding-kit.mdc`, or `.clinerules`.
3. Point agents back to `AGENTS.md`, `BOOTSTRAP.md`, `HANDOFF.md`, `MAINTAINERS.md`, `kit.yaml`, and local search commands.
4. After adapter changes, validate, rebuild the index, regenerate session bootstrap, and run a representative search.

For learner step guidance:

1. Read `AGENTS.md`.
2. Read `skills/onboarding-buddy/SKILL.md`.
3. Read `kit.yaml`.
4. Read the learner state file if present.
5. Read only the current module's `module.yaml` and `steps.yaml`.
6. Read `knowledge.md` or `faq.yaml` only when the current step or question needs it.

For random questions:

1. Run `python3 scripts/search_knowledge.py "<question>" --module <current-module>` when a current module exists.
2. Open only the cited top results needed to answer.
3. Check `sources/source-manifest.yaml` before trusting source corpus files.
4. Cite `module_id`, source path, heading, and manifest item when relevant.
5. If no cited source supports the answer, say it is unresolved and route to the module owner.

Do not read the whole corpus by default. Do not answer from memory when local indexed content can answer. The only full-package orientation exception is the explicit first-run bootstrap flow above.

## CRUD Rules By Layer

### Kit And Journeys

- Create/update journeys only in `kit.yaml`.
- Every journey module must exist under `modules/`.
- Every module in `module_order` must exist under `modules/`.
- Do not remove a module directory just because a journey no longer uses it.
- After changing journeys, run validation and indexing.

### Modules

- Create: use `python3 scripts/module_crud.py create <module-id> --title "<title>" --owner "<owner>"`.
- Read/list: use `python3 scripts/module_crud.py list` or inspect `modules/<module-id>/module.yaml`.
- Update: edit only that module's `module.yaml`, `steps.yaml`, `knowledge.md`, and `faq.yaml`; bump `version` and `last_reviewed` for substantive changes.
- Disable: use `python3 scripts/module_crud.py disable <module-id>`, then remove it from active journeys if needed.
- Delete: do not delete by default. Only delete when a maintainer explicitly asks for irreversible removal and after preserving source evidence elsewhere.

### Module Metadata

`module.yaml` must contain:

- `id`, matching the directory name.
- `title`.
- semver `version`.
- `type`: `setup`, `learning`, `workflow`, `acceptance`, or `lifecycle`.
- `owner`.
- `audience`.
- `sensitivity`: `public`, `internal`, or `confidential`.
- `prerequisites`.
- `outputs`.
- `entry_step`, which must exist in `steps.yaml`.
- `source_refs`.
- `last_reviewed`.
- `enabled`.

### Steps

- Step ids must be unique within the module.
- Each step must include `id`, `title`, `goal`, `instructions`, `completion`, and `blockers`.
- `next_step` may only reference a step in the same module.
- Cross-module prerequisites belong in `module.yaml`, not `next_step`.
- Every `help_refs` file path must stay inside the kit root.
- Step responses must show one step only and wait for explicit completion before advancing.

### FAQ And Knowledge

- `faq.yaml` must keep a `faqs:` root.
- FAQ entries must include question patterns, answer, related steps, source refs, and escalation owner.
- `knowledge.md` should explain concepts and local process; it must not override `steps.yaml`.
- Do not put passwords, tokens, identity numbers, bank cards, or raw credential material in FAQ or knowledge.

### Sources And Assets

- Follow `sources/README.md`.
- Binary originals go under `assets/`.
- Searchable extracted text goes under `sources/`.
- Every source must appear in `sources/source-manifest.yaml`.
- Unmanifested material cannot be used as answer evidence.
- After source changes, run ingestion when relevant, then validation and indexing.

### State

- Runtime state must follow `state-template/onboarding-run.schema.json`.
- Do not store sensitive credentials in state.
- Update state after each completed step before presenting the next step.
- Record unresolved questions with citations or escalation status.

### Search Index

- `search/chunks.jsonl` and `search/index.json` are generated.
- Never hand-edit search files.
- Rebuild with `python3 scripts/index_knowledge.py` after module or source changes.
- Verify important changes with `python3 scripts/search_knowledge.py "<query>"`.

### Depth Context

- Keep `AGENTS.md` compact and operational.
- Store deeper intent, workspace map, state ledger, eval checklists, and systemization backlog in `.ai/context/`.
- Before meaningful architecture or maintenance work, read `.ai/context/README.md` and the smallest relevant context file.
- After meaningful work, update `.ai/context/04-state-ledger.md`.
- When repeated work appears three times, update `.ai/context/06-systemization.md` or create a reusable asset.

## Required Verification

Run these before packaging or reporting completion:

```bash
python3 scripts/validate_kit.py
python3 scripts/index_knowledge.py
python3 scripts/bootstrap_session.py
python3 scripts/search_knowledge.py "<representative query>"
```

For source changes from the primary Feishu document, run this before validation:

```bash
python3 scripts/ingest_lark_sources.py
```

For skill installation checks:

```bash
python3 scripts/install_skill.py --dry-run
```

## Packaging

Package only with:

```bash
python3 scripts/package_kit.py
```

If Python 3.10+ is unavailable, run packaging through the optional uv bootstrap after user approval:

```bash
# Windows
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1

# macOS/Linux
sh bootstrap.sh
```

Rules:

1. Do not use PowerShell `Compress-Archive`, Finder compression, or manual zip tools.
2. The zip filename must match `kit.yaml` version, for example `onboarding-kit-v0.1.7.zip`.
3. The zip must not contain `state/` or any learner runtime data.
4. The package script must run validation, indexing, session bootstrap, a representative search, and zip self-test.
5. The zip must contain the required root files, `.ai/context/README.md`, the six numbered context files, `sources/source-manifest.yaml`, `search/index.json`, and `search/chunks.jsonl`.
