42 lines
2.2 KiB
Markdown
42 lines
2.2 KiB
Markdown
# 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`](design/overview.md) — the system map.
|
|
2. [`design/context-history.md`](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`](design/pod-session-state.md) — Pod identity, replayable session logs, current metadata, and live process hints.
|
|
4. [`design/profiles-manifests-prompts.md`](design/profiles-manifests-prompts.md) — reusable Profiles, resolved Manifests, and prompt resources.
|
|
5. [`design/tool-permissions-scope.md`](design/tool-permissions-scope.md) — tool policy and filesystem scope.
|
|
6. [`design/memory-knowledge.md`](design/memory-knowledge.md) — generated memory, Knowledge, and audit records.
|
|
7. [`development/work-items.md`](development/work-items.md) — how project work is recorded and reviewed.
|
|
8. [`development/validation.md`](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.
|