yoi/docs/README.md

Yoi documentation

This directory contains maintained developer documentation for Yoi. Its job is to preserve design intent that is hard to recover from code alone.

It is not a dumping ground for external research, old plans, API inventories, or ticket history. Those belong in local notes, work item artifacts, code, or git history.

Reading order

1. design/overview.md — the system map.
2. design/context-history.md — the highest-risk invariant: inputs that affect the model must be committed to history before they enter context.
3. design/pod-session-state.md — Pod identity, replayable session logs, current metadata, and live process hints.
4. design/profiles-manifests-prompts.md — reusable Profiles, resolved Manifests, and prompt resources.
5. design/tool-permissions-scope.md — tool policy and filesystem scope.
6. design/memory-knowledge.md — generated memory, Knowledge, and audit records.
7. development/work-items.md — how project work is recorded and reviewed.
8. development/validation.md — how to check changes.

What belongs here

Keep documentation when it records a stable design boundary, a non-obvious rationale, or a workflow that future changes must respect.

Examples that belong:

• Why Pod metadata is not the session log.
• Why Profile and resolved Manifest are different layers.
• Why context-only event injection is forbidden.
• Why child Pod notifications are hints rather than completion proof.

What does not belong here

Do not keep material only because it once helped a ticket.

Examples that should be removed or moved to docs/.local/ / work item artifacts:

• External project comparisons.
• Provider API snapshots, prices, or model tables.
• Old implementation plans that are no longer the design authority.
• Public type or method inventories that drift with code.
• Debug notes that are useful only for one investigation.

docs/.local/ is intentionally outside the maintained documentation surface.