# Rules And Stable Context

## Authority

- `AGENTS.md` is the compact operating contract loaded first.
- `MAINTAINERS.md` is the strict CRUD, read-scope, verification, and packaging contract.
- `kit.yaml` owns journey order, module order, owners, and search paths.
- `skills/onboarding-buddy/SKILL.md` owns the skill entrypoint and learner/maintainer workflows.
- `.ai/context/*` stores deeper intent, workspace maps, state, checklists, and systemization backlog. Load only the relevant file for the task.

## Progressive Disclosure Standard

中文术语：渐进式披露、查询范围、读什么范围、读什么文档、最小充分上下文。

Use the smallest sufficient context surface:

- Start or continue onboarding: read `AGENTS.md`, `skills/onboarding-buddy/SKILL.md`, `kit.yaml`, learner state, then only the current module's `module.yaml` and `steps.yaml`.
- Answer a question: run `python3 scripts/search_knowledge.py "<question>"`; open only the top cited files needed to answer.
- Source-backed answer: check `sources/source-manifest.yaml` before trusting source corpus files.
- Module maintenance: read `MAINTAINERS.md`, then only the affected module files.
- Source maintenance: read `sources/README.md`, `sources/source-manifest.yaml`, and the relevant source/extraction files.
- Architecture or resume work: read `.ai/context/README.md`, then the specific `.ai/context/*` file that matches the layer being changed.

Do not read the whole corpus by default. Do not treat binary assets as searchable evidence unless an extracted text file exists.

## Module Rules

- New modules must contain `module.yaml`, `steps.yaml`, `knowledge.md`, and `faq.yaml`.
- Step flow lives in `steps.yaml`; knowledge and FAQ files cannot override flow.
- `entry_step` must exist in `steps.yaml`.
- `next_step` must stay inside the same module.
- Cross-module sequencing belongs in `kit.yaml` and module prerequisites.
- Disabling is preferred over deletion.

## Source Rules

- `assets/` stores binary originals.
- `sources/` stores searchable text and metadata.
- Every source must appear in `sources/source-manifest.yaml`.
- Unmanifested source material cannot be used as answer evidence.
- Raw signed Feishu asset URLs, credentials, tokens, identity numbers, bank cards, and full credential documents must not enter searchable text.

## State Rules

- Learner runtime state follows `state-template/onboarding-run.schema.json`.
- Project/maintainer state lives in `.ai/context/04-state-ledger.md`.
- Update learner state before showing the next learner step.
- Update project state after meaningful maintenance, ingestion, packaging, or architecture changes.

## Safety And Privacy

- Never ask users to paste passwords, verification codes, access tokens, private keys, ID numbers, bank card numbers, or credential documents.
- Account steps may describe application path, owner, permission boundary, and recovery path only.
- If sensitive data appears in chat or sources, redact it and route to the approved owner.

## Visual Trust

- When learners or candidates may distrust pure text, prefer pairing concise instructions with official or redacted images/flowcharts that are listed in `sources/source-manifest.yaml`.
- Send or reference only images with matching `sources/image-notes/` descriptions.
- Do not send raw screenshots that expose candidate information, employee names/avatars, phone numbers, IDs, bank cards, verification codes, meeting links, internal URLs, raw signed Feishu asset URLs, or permission materials.
- If the interface supports local image display, resolve the asset path from the kit root and render it as a Markdown image with an absolute filesystem path.
- If the interface cannot display local images, provide the image path and summarize the matching image note.

## Anti-Patterns

- Dumping the entire journey when the learner needs one step.
- Answering from memory when local indexed evidence exists.
- Citing a PDF, image, or video without an extracted text or description file.
- Editing `search/chunks.jsonl` or `search/index.json` by hand.
- Adding long background to `AGENTS.md` instead of `.ai/context/`.
- Treating generated scaffold files or TODO-heavy files as completed context.
