docs: reorganize developer documentation

docs/development/dogfooding.md

@@ -0,0 +1,26 @@
+# Dogfooding Yoi
+
+This repository is developed with Yoi itself. Dogfooding is valuable because it exposes orchestration, memory, TUI, and workflow problems under real use.
+
+## What to record
+
+When a tool limitation, workflow obstacle, or model-facing policy problem blocks work, record it under `docs/report/` or a work item artifact. Do not turn every minor annoyance into a maintained design doc.
+
+A report is useful when it explains:
+
+- what the agent/user tried to do
+- what made the work unsafe, confusing, or slow
+- what design boundary was missing
+- what evidence was observed
+
+## Runtime command caveat
+
+After rebuilding and restarting during dogfooding, `current_exe()` can point at a deleted binary path. Use typed runtime-command configuration and the development-only `YOI_POD_RUNTIME_COMMAND` executable override rather than reviving shell-command overrides.
+
+## Multi-Pod work
+
+Use child Pods for scoped tasks and reviews, but keep orchestration decisions in visible project records. Do not merge, close, or clean up merely because a child notification arrived.
+
+## Secrets and logs
+
+Do not put secrets, private prompts, or ignored secret-like file contents into diagnostics, work items, docs, session logs, or model context. During broad audits, existence/path checks are enough unless the user explicitly asks to inspect content.

docs/development/environment.md

@@ -0,0 +1,24 @@
+# Environment boundary
+
+Environment variables are a minimized runtime boundary. Prefer explicit profile/manifest configuration and secret references over ambient process state.
+
+## Why minimize environment variables
+
+Ambient environment is hard to audit: it can differ between shells, services, spawned Pods, tests, and restored processes. If important runtime behavior depends on it, reproducing a session becomes harder.
+
+Yoi keeps environment variables for narrow bootstrap and development cases, while normal provider credentials and runtime configuration should be explicit records.
+
+## Principles
+
+- Distinguish data/runtime paths from resource/config paths.
+- Prefer embedded builtin resources over installed runtime resource directories.
+- Use explicit secret refs for provider and WebSearch credentials.
+- Keep dev-only executable overrides clearly named and documented.
+- Avoid shell-command parser overrides for runtime Pod launch.
+- Tests should prefer typed fixtures/injection and mutate process environment only around thin env-reader behavior.
+
+## Current surface
+
+Use `YOI_*` for current environment variables. Old project prefixes should not be reintroduced.
+
+`YOI_POD_RUNTIME_COMMAND` is a development-only executable-path override for typed `yoi pod` launch. It is not a general shell-command override.

docs/development/validation.md

@@ -0,0 +1,47 @@
+# Validation
+
+Validation should match the change. Do not run expensive broad checks just to look thorough, but do not skip checks that prove the changed boundary still works.
+
+## Docs-only changes
+
+Minimum checks:
+
+```sh
+./tickets.sh doctor
+git diff --check
+```
+
+Useful stale-surface sweeps:
+
+```sh
+STALE_DOC_PATTERN='TODO[.]md|obsolete doc dirs|old ticket surface'
+rg -n "$STALE_DOC_PATTERN" README.md docs crates/*/README.md --glob '!docs/report/**'
+```
+
+## Code changes
+
+Prefer targeted tests first, then broader checks when the touched boundary is central.
+
+Common checks:
+
+```sh
+cargo test --workspace
+cargo test -p <crate>
+cargo check --workspace
+```
+
+Avoid repository-wide formatting churn when a validation failure is caused by pre-existing unrelated formatting.
+
+## Work item checks
+
+Run:
+
+```sh
+./tickets.sh doctor
+```
+
+Use work item review to verify that the implementation satisfies the ticket, not only that the diff looks plausible.
+
+## Current limitation
+
+End-to-end tests that spawn real processes are not yet designed. When changing Pod restoration, socket behavior, or orchestration, compensate with targeted unit/integration tests and concrete manual evidence in the implementation report.

docs/development/work-items.md

@@ -0,0 +1,43 @@
+# Work items
+
+Yoi project work is tracked through `work-items/` and `./tickets.sh`. Git history plus work item files are the authoritative state-transition record.
+
+Do not treat ad-hoc chat summaries, memory records, or Pod notifications as the final source of project state.
+
+## Basic commands
+
+```sh
+./tickets.sh create --title "..." [--slug slug] [--kind task] [--priority P2] [--label a,b]
+./tickets.sh list [--status open|pending|closed|all]
+./tickets.sh show <id-or-slug>
+./tickets.sh comment <id-or-slug> [--role comment|plan|decision|implementation_report] [--file path]
+./tickets.sh review <id-or-slug> --approve|--request-changes [--file path]
+./tickets.sh status <id-or-slug> open|pending|closed
+./tickets.sh close <id-or-slug> [--resolution text|--file path]
+./tickets.sh doctor
+```
+
+## Granularity
+
+One work item should describe a complete change that can be explained as a feature, behavior, design decision, or maintenance outcome when closed.
+
+Avoid tickets that only mirror an implementation step unless that step is independently reviewable and useful. Phase/step lists inside a ticket are execution order, not a separate dependency system.
+
+## Contents
+
+A useful work item states:
+
+- background and motivation
+- requirements
+- acceptance criteria
+- relevant constraints
+- review/implementation reports when work is submitted
+- final resolution when closed
+
+Keep long research dumps out of the item body. Put necessary artifacts under the ticket's `artifacts/` directory and summarize the conclusion in the thread.
+
+## Workflow
+
+Create or refine the work item before opening a separate implementation worktree. When using child Pods, the orchestrator should provide a scoped task and later verify concrete evidence: diff, tests, worktree status, and child output.
+
+Closing a ticket means the repository records are ready, not merely that a child Pod announced completion.

docs/development/workflows.md

@@ -0,0 +1,36 @@
+# Workflows and orchestration
+
+Yoi development uses workflows to make multi-step agent work repeatable without hiding authority in chat state.
+
+Project-authored workflows live under `.yoi/workflow/`. Generated memory lives under `.yoi/memory/`; the two should not be mixed.
+
+## Workflow role
+
+A workflow should define how to coordinate work. It should not become a private implementation branch, an unreviewed design decision, or a replacement for work items.
+
+Current workflow themes include:
+
+- preflight before delegating uncertain ticket work
+- worktree setup and cleanup
+- sibling coder/reviewer Pod orchestration
+- human-gated maintenance and merge readiness
+
+## Child Pods
+
+Spawned Pods are useful for scoped implementation, review, or exploration. They are not independent project authorities.
+
+A parent/orchestrator must verify:
+
+- child output via `ReadPodOutput`
+- live/restorable state via Pod tools when relevant
+- worktree status and diff
+- validation command output
+- work item requirements and acceptance criteria
+
+Notifications are hints to inspect state. They are not proof of completion.
+
+## Merge and close responsibility
+
+Unless explicitly authorized otherwise, final merge, cleanup, design-boundary decisions, and ticket closure remain the orchestrator/human responsibility.
+
+Child Pods may commit in delegated worktrees when the workflow allows it, but the merge-ready dossier should make the final decision auditable from repository records.