docs: reorganize developer documentation

2026-06-01 20:59:32 +09:00
parent e6c458021c
commit 9dcbd4c3e0
83 changed files with 1320 additions and 5649 deletions
@@ -0,0 +1,30 @@
+# client
+
+## Role
+
+`client` contains reusable socket-client and runtime-command mechanics for talking to Pods from CLI/TUI code.
+
+## Boundaries
+
+Owns:
+
+- one-shot Pod socket client behavior
+- request/reply delivery mechanics
+- runtime command construction below the product façade
+- shared attach/status probing helpers used by higher layers
+
+Does not own:
+
+- product command names (`yoi`)
+- Pod state authority (`pod`, `pod-store`, `session-store`)
+- UI rendering (`tui`)
+- Worker turn semantics (`llm-worker`)
+
+## Design notes
+
+The client boundary lets `tui` and `yoi` share Pod communication without making library crates depend on the product binary. Socket clients should drain connect-time snapshot/alert traffic before sending a method or deciding status.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
+- [`../../docs/design/overview.md`](../../docs/design/overview.md)
@@ -1,9 +1,25 @@
 # daemon

-Pod のライフサイクルを管理する常駐デーモン。未実装。
+## Role

-## 依存クレート
+`daemon` is reserved for future long-lived Pod lifecycle management.

- `manifest` — マニフェスト設定
- `protocol` — 通信プロトコル型
- `tokio` — 非同期ランタイム
+## Boundaries
+
+Owns:
+
+- daemon-specific lifecycle coordination when that design is implemented
+
+Does not own today:
+
+- current Pod socket serving (`pod`)
+- normal CLI/TUI startup (`yoi`, `tui`)
+- live registry mechanics already handled elsewhere (`pod-registry`)
+
+## Design notes
+
+This crate exists as a placeholder. Do not route current runtime authority through it until there is a concrete daemon design and work item.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
@@ -0,0 +1,28 @@
+# lint-common
+
+## Role
+
+`lint-common` contains shared linting primitives for structured project records.
+
+## Boundaries
+
+Owns:
+
+- reusable frontmatter/slug/path validation helpers
+- common lint diagnostic shapes used by higher-level crates
+
+Does not own:
+
+- memory-specific policy (`memory`)
+- workflow-specific policy (`workflow`)
+- product CLI command shape (`yoi`)
+- work item script behavior (`tickets.sh`)
+
+## Design notes
+
+Keeping common lint mechanics here avoids duplicating low-level validation while leaving each record type's policy in its owning crate.
+
+## See also
+
+- [`../../docs/design/memory-knowledge.md`](../../docs/design/memory-knowledge.md)
+- [`../../docs/development/work-items.md`](../../docs/development/work-items.md)
@@ -1,9 +1,27 @@
 # llm-worker-macros

-Rust メソッドを LLM 呼び出し可能なツールとして自動登録する手続きマクロクレート。引数構造体・Tool トレイト実装・ToolDefinition を自動生成する。
+## Role

-## 公開マクロ
+`llm-worker-macros` provides procedural macros for declaring Rust methods as LLM-callable tools.

- `#[tool_registry]` — impl ブロックに付与し、内部の `#[tool]` メソッドを一括処理
- `#[tool]` — メソッドをツールとしてマーク
- `#[description = "..."]` — 引数に説明を付与（JSON Schema の description に反映）
+## Boundaries
+
+Owns:
+
+- compile-time generation of tool argument structures and definitions
+- small macro conveniences around tool descriptions and schemas
+
+Does not own:
+
+- runtime permission decisions
+- filesystem scope checks
+- tool execution policy
+- model/tool-loop orchestration
+
+## Design notes
+
+Macros reduce boilerplate, but they must not imply capability. A generated tool definition is still subject to manifest permissions, Pod scope, and runtime policy.
+
+## See also
+
+- [`../../docs/design/tool-permissions-scope.md`](../../docs/design/tool-permissions-scope.md)
@@ -1,23 +1,32 @@
 # llm-worker

-LLM との対話を管理する低レベル基盤クレート。会話履歴、ツール実行、イベントストリーミング、ライフサイクルフックを統合した `Worker` 抽象を提供する。
+## Role

-## 公開型
+`llm-worker` owns provider-independent model turn orchestration over committed history, tools, callbacks, retries, continuation, pruning, and compaction boundaries.

-### コア
+## Boundaries

- `Worker<C, S>` — LLM 対話の中央管理（ターン実行、ツール呼び出し、キャンセル）
- `WorkerConfig` / `WorkerResult` / `WorkerError` — 設定・実行結果・エラー
- `Item` / `ContentPart` / `Role` — 会話履歴の構成要素
+Owns:

-### モジュール
+- Worker history mutation and append contracts
+- tool-call loop semantics
+- pre-stream retry and stream-started continuation policy
+- pruning/compaction coordination from the Worker perspective
+- provider-neutral events/callbacks/interceptors

- `llm_client` — プロバイダ抽象（`LlmClient` トレイト、`Request`, `RequestConfig`, Anthropic/OpenAI/Gemini/Ollama 実装）
- `tool` — ツール定義・実行（`Tool` トレイト、`ToolDefinition`, `ToolOutput`, サイズ判定による Inline/Stored 切替）
- `tool_server` — ツール登録・ルックアップ（`ToolServer`, `ToolServerHandle`）
- `hook` — 実行フローへの介入ポイント（`Hook` トレイト、`PreToolCall`, `PostToolCall`, `OnTurnEnd` など）
- クロージャベースイベント購読（`Worker::on_text_block()`, `on_tool_use_block()`, `on_usage()` 等）
- `timeline` — イベントストリームのディスパッチ（`Handler` トレイト、各ブロックコレクター）。パワーユーザー向けに `timeline_mut()` も提供
- `event` — ストリーミングイベント型（`Event`, `BlockStart`, `BlockDelta` など）
- `state` — 型状態パターンによるキャッシュ保護（`Mutable` / `CacheLocked`）
-cratesの整理Add READMEsRE to all crates@@
+Does not own:
+
+- Pod names, sockets, process lifecycle, or scope delegation (`pod`)
+- product CLI shape (`yoi`)
+- provider catalog and secret resolution (`provider`, `secrets`)
+- durable Pod current state (`pod-store`)
+
+## Design notes
+
+The Worker is where turn lifecycle belongs because it sees history, in-flight usage, partial output, and tool-call state. It should not receive context-only volatile facts; model-affecting inputs must first be appended to history.
+
+## See also
+
+- [`../../docs/design/context-history.md`](../../docs/design/context-history.md)
+- [`../../docs/design/compaction.md`](../../docs/design/compaction.md)
+- [`../../docs/design/provider-model-boundary.md`](../../docs/design/provider-model-boundary.md)
@@ -1,14 +1,31 @@
 # manifest

-Pod の宣言的設定を TOML マニフェストとして定義・パースするクレート。モデル設定、ワーカー設定、ディレクトリスコープ制約を記述できる。
+## Role

-## 公開型
+`manifest` resolves reusable profile/configuration inputs into the concrete runtime Manifest used to create or restore Pods.

- `PodManifest` — Pod 設定全体（`from_toml()` でパース）
- `PodMeta` — Pod メタデータ（名前、pwd）
- `ModelConfig` — LLM モデル設定（scheme、base_url、model_id、auth）
- `SchemeKind` — wire scheme 種別（`Anthropic`, `OpenaiChat`, `OpenaiResponses`, `Gemini`）
- `AuthRef` — 認証参照（`None`, `ApiKey { env, file }`, `CodexOAuth`）
- `WorkerManifest` — ワーカー設定（システムプロンプト、生成設定、reasoning）
- `ScopeConfig` / `ScopeRule` / `Permission` — allow / deny の宣言的スコープ設定
- `Scope` — 実行時スコープ。`from_config(&ScopeConfig, pwd)` で構築し、`is_readable` / `is_writable` / `permission_at` で問い合わせる
+## Boundaries
+
+Owns:
+
+- Profile and Manifest data structures
+- source/partial/resolved configuration layering
+- path and prompt-resource resolution
+- tool permission and filesystem scope configuration types
+- model/provider references as configuration records
+
+Does not own:
+
+- provider HTTP clients or secret lookup implementation (`provider`, `secrets`)
+- Pod lifecycle (`pod`)
+- product CLI parsing (`yoi`)
+- generated memory records (`memory`)
+
+## Design notes
+
+Profiles are reusable recipes; resolved Manifests are runtime contracts. Keep runtime-bound fields such as Pod name, concrete delegated scope, sockets, session pointers, and raw secrets out of reusable Profiles.
+
+## See also
+
+- [`../../docs/design/profiles-manifests-prompts.md`](../../docs/design/profiles-manifests-prompts.md)
+- [`../../docs/design/tool-permissions-scope.md`](../../docs/design/tool-permissions-scope.md)
@@ -0,0 +1,31 @@
+# memory
+
+## Role
+
+`memory` owns generated memory, Knowledge records, staging/consolidation mechanics, linting, and audit observations.
+
+## Boundaries
+
+Owns:
+
+- memory/Knowledge record parsing and validation
+- memory lint subcommand backend behavior
+- staging and consolidation file mechanics
+- audit log observation writes
+- generated memory prompt support where it belongs below the CLI
+
+Does not own:
+
+- authoritative project records (`work-items/`, git history)
+- normal Pod turn orchestration (`llm-worker`)
+- product CLI command shape (`yoi`)
+- curated workflow definitions (`workflow`)
+
+## Design notes
+
+Memory is useful context, not authority. It should preserve small durable preferences and rationale without duplicating tickets, docs, or implementation reports.
+
+## See also
+
+- [`../../docs/design/memory-knowledge.md`](../../docs/design/memory-knowledge.md)
+- [`../../docs/development/work-items.md`](../../docs/development/work-items.md)
@@ -0,0 +1,30 @@
+# pod-registry
+
+## Role
+
+`pod-registry` tracks live Pod process ownership and delegated scope locks at runtime.
+
+## Boundaries
+
+Owns:
+
+- machine-local live Pod registration
+- collision detection for running Pod names
+- delegated scope lock bookkeeping
+- registry cleanup hooks for stopped or unreachable children
+
+Does not own:
+
+- durable Pod metadata (`pod-store`)
+- replayable session logs (`session-store`)
+- socket protocol definitions (`protocol`)
+- project work item state
+
+## Design notes
+
+The registry is a runtime coordination mechanism. It can help decide whether a Pod is live or colliding, but durable visibility/restoration should be backed by Pod metadata when possible.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
+- [`../../docs/design/tool-permissions-scope.md`](../../docs/design/tool-permissions-scope.md)
@@ -0,0 +1,30 @@
+# pod-store
+
+## Role
+
+`pod-store` owns current Pod metadata keyed by Pod name.
+
+## Boundaries
+
+Owns:
+
+- persisted Pod metadata files
+- current active/pending session pointers
+- resolved manifest snapshots for restoration
+- parent-visible spawned-child metadata
+- restoration labels and diagnostics derived from metadata
+
+Does not own:
+
+- replayable conversation logs (`session-store`)
+- live process locks or socket reachability (`pod-registry`, `client`)
+- product CLI behavior (`yoi`)
+- model turn execution (`llm-worker`)
+
+## Design notes
+
+Pod metadata is intentionally thin. It should answer current-state questions without duplicating transcripts or becoming a second session log.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
@@ -1,22 +1,32 @@
 # pod

-独立したエージェント実行単位「Pod」を実装するクレート。LLM ワーカーセッションをマニフェスト設定・ファイルスコープ制約と組み合わせ、Unix ソケット経由の双方向通信で操作可能にする。
+## Role

-## 公開型
+`pod` turns an `llm-worker` Worker into a named runtime entity with manifest configuration, scoped tools, session persistence, protocol handling, and Pod metadata integration.

-### コア
+## Boundaries

- `Pod<C, St>` — LLM ワーカーセッション + マニフェスト + スコープのラッパー（`run()`, `resume()`, `from_manifest()`）
- `PodRunResult` — 実行結果（`Finished`, `Paused`）
- `PodError` — エラー型
+Owns:

-### 制御
+- Pod lifecycle and socket protocol serving
+- Worker construction around a resolved Manifest
+- session-store and pod-store coordination
+- built-in tool registration under scope/policy
+- spawned-child orchestration hooks

- `PodController` — Pod ライフサイクルを管理するアクター（`spawn()` でタスク起動）
- `PodHandle` — Pod への操作ハンドル（`send()`, `subscribe()`）
- `PodSharedState` / `PodStatus` — 共有状態（`Idle`, `Running`, `Paused`）
+Does not own:

-### ランタイム
+- provider-specific wire formats (`provider` / `llm-worker` clients)
+- product CLI parsing (`yoi`)
+- TUI display authority (`tui`)
+- current-state storage schema outside Pod metadata (`pod-store`)

- `RuntimeDir` — `$XDG_RUNTIME_DIR/yoi/{pod_name}/` 配下のランタイムディレクトリ管理（ステータス・履歴のアトミック書き込み）
- `SocketServer` — Pod Protocol 用 Unix ソケットサーバー
+## Design notes
+
+A Pod is runtime authority, not UI state. It should commit model-visible events through history/session paths and keep current Pod-name state in Pod metadata rather than in transient runtime files.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
+- [`../../docs/design/context-history.md`](../../docs/design/context-history.md)
+- [`../../docs/design/tool-permissions-scope.md`](../../docs/design/tool-permissions-scope.md)
@@ -1,10 +1,31 @@
 # protocol

-クライアントとPod間の通信プロトコルを定義するクレート。Unix ソケット上で JSON Lines として送受信されるメッセージ型を提供する。
+## Role

-## 公開型
+`protocol` defines the JSONL message boundary between Pod clients and Pod servers.

- `Method` — クライアント→Pod のコマンド（`Run`, `Resume`, `Cancel`）
- `Event` — Pod→クライアント のイベント（`TurnStart`, `TextDelta`, `ToolCallStart`, `Usage`, `Error` など）
- `TurnResult` — ターン完了状態（`Finished`, `Paused`）
- `ErrorCode` — エラー分類（`AlreadyRunning`, `ProviderError`, `ToolError` など）
+## Boundaries
+
+Owns:
+
+- transport-neutral method/event/result types
+- request/reply and broadcast event shapes
+- protocol error categories shared by clients and servers
+
+Does not own:
+
+- Unix socket implementation details (`client`, `pod`)
+- TUI rendering (`tui`)
+- Worker history semantics (`llm-worker`)
+- durable storage (`session-store`, `pod-store`)
+
+## Design notes
+
+The exact enum variants are code authority. The README should describe the boundary, not duplicate every message shape.
+
+Protocol events can inform UI and orchestration, but durable state changes still need to flow through Pod/session/metadata records.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
+- [`../../docs/design/context-history.md`](../../docs/design/context-history.md)
@@ -1,21 +1,33 @@
 # provider

-マニフェストの `ModelManifest` から適切な `LlmClient`（`HttpTransport<S>`）を構築するファクトリクレート。プロバイダ / モデルカタログの解決、API キーの local secret store / 明示ファイル解決、scheme ↔ auth の整合検証を担う。
+## Role

-## 公開型
+`provider` resolves model/provider configuration and constructs provider-specific LLM clients for `llm-worker`.

- `build_client(manifest: &ModelManifest) -> Result<Box<dyn LlmClient>, ProviderError>` — ref / inline を受け取り、カタログ解決 → `HttpTransport<S>` 構築までを行う
- `build_client_from_config(config: &ModelConfig) -> Result<Box<dyn LlmClient>, ProviderError>` — 解決済み `ModelConfig` から構築
- `catalog::resolve_model_manifest(&ModelManifest) -> Result<ModelConfig, ResolveError>` — ref / inline を `ModelConfig` へ解決（build せずに参照のみ欲しいケース向け）
- `catalog::{load_providers, load_models}` — builtin + user override を解決したカタログ
- `ProviderError` / `CatalogError` / `catalog::ResolveError` — エラー種別
+## Boundaries

-## 責務
+Owns:

- プロバイダ / モデルカタログの builtin (`resources/{providers,models}/builtin.toml`) と user override (`$XDG_CONFIG_HOME/yoi/{providers,models}.toml`) の解決
- `ModelManifest` の ref 形を `(provider, model_id)` に split し、`ModelConfig` へ展開
- `AuthRef::SecretRef` / `AuthRef::ApiKey` を `ResolvedAuth::ApiKey` に解決（通常は local secret store、低レベル manifest では明示ファイルも可）
- `AuthRef::None` / `AuthRef::CodexOAuth` の解決
- `Scheme::required_auth()` と `ResolvedAuth` の妥当性検証（非対応組合せは構築エラー）
- capability は manifest 明示 > model catalog > provider.default_capability > `Scheme::default_capability()` の順で解決
- context window は manifest 明示 > model catalog > provider.default_context_window > builtin fallback の順で解決し、inline model でも `context_window` で override できる
+- builtin and user provider/model catalog resolution
+- model reference expansion into concrete model config
+- auth reference resolution through supported mechanisms
+- provider/scheme capability and context-window metadata
+- provider-specific client construction
+
+Does not own:
+
+- Worker turn lifecycle (`llm-worker`)
+- secret storage internals (`secrets`)
+- Pod lifecycle (`pod`)
+- product CLI parsing (`yoi`)
+
+## Design notes
+
+Provider API facts drift. Keep wire-format, auth, catalog, and capability differences here so Worker semantics remain stable.
+
+Codex OAuth is a separate integration from normal provider secret refs because its local file shape and lifecycle differ.
+
+## See also
+
+- [`../../docs/design/provider-model-boundary.md`](../../docs/design/provider-model-boundary.md)
+- [`../../docs/design/profiles-manifests-prompts.md`](../../docs/design/profiles-manifests-prompts.md)
@@ -0,0 +1,30 @@
+# secrets
+
+## Role
+
+`secrets` provides the local secret reference store used by provider and tool configuration.
+
+## Boundaries
+
+Owns:
+
+- provider-independent secret id to value lookup
+- modest plaintext-at-rest reduction and integrity checks
+- secret store file format and validation
+
+Does not own:
+
+- provider-specific auth protocol (`provider`)
+- Codex OAuth local integration shape (`provider`)
+- prompting or model context
+- work item or diagnostic redaction policy outside its API surface
+
+## Design notes
+
+The store is not a high-assurance keychain. It exists to avoid scattering plaintext credentials through config files and logs, not to provide strong local adversary protection.
+
+Secret values must stay out of diagnostics, Debug output, CLI/TUI output, work items, docs, session logs, model context, and persisted plaintext files.
+
+## See also
+
+- [`../../docs/design/provider-model-boundary.md`](../../docs/design/provider-model-boundary.md)
@@ -0,0 +1,29 @@
+# session-metrics
+
+## Role
+
+`session-metrics` records usage and memory/session metrics that are useful for diagnostics and maintenance.
+
+## Boundaries
+
+Owns:
+
+- metric record types and persistence helpers
+- explicit memory usage/read/reference observations where applicable
+- lightweight diagnostic data that should not become model context by itself
+
+Does not own:
+
+- prompt context packing (`llm-worker`)
+- generated memory contents (`memory`)
+- provider billing semantics (`provider`)
+- UI status rendering (`tui`)
+
+## Design notes
+
+Metrics are observations. They may guide compaction, memory effectiveness analysis, or UX, but they are not authoritative conversation history and should not smuggle hidden state into model input.
+
+## See also
+
+- [`../../docs/design/memory-knowledge.md`](../../docs/design/memory-knowledge.md)
+- [`../../docs/design/compaction.md`](../../docs/design/compaction.md)
@@ -1,29 +1,32 @@
-# llm-worker-persistence
+# session-store

-Worker のセッション永続化を提供するクレート。追記専用の JSONL ログとして状態遷移を記録し、ログの再生によってセッションを完全に復元する。大きなツール出力は Blob ストアに分離保存する。
+## Role

-## 公開型
+`session-store` owns replayable append-only session logs.

-### セッション
+## Boundaries

- `Session<C, St>` — Worker をラップした永続化セッション（`run()`, `resume()`, `fork()`, `fork_at()`）
- `SessionId` — UUID v7 によるセッション識別子
- `SessionConfig` — 永続化設定（イベントトレース記録の有無）
+Owns:

-### ストア
+- session identifiers and segment lineage
+- JSONL log entries for replayable conversation/runtime history
+- restoring Worker/session state from committed records
+- schema surfaces that should make drift compile-visible

- `Store` トレイト — 永続化バックエンド抽象（`append`, `read_all`, `list_sessions`）
- `FsStore` — ファイルシステム上の JSONL ストア実装
- `BlobStore` トレイト — Blob ストレージ抽象（`store`, `load`）
- `FsBlobStore` — ファイルシステム上の Blob ストア実装
- `BlobOutputProcessor` — ToolOutputProcessor 実装（小さい出力はインライン、大きい出力は Blob 保存）
+Does not own:

-### ログ
+- current Pod-name metadata (`pod-store`)
+- live process/socket discovery (`pod-registry`, `client`)
+- UI state (`tui`)
+- generated memory summaries (`memory`)

- `LogEntry` — セッションログのエントリ型（`SegmentStart`, `UserInput`, `AssistantItem`, `ToolResult`, `SystemItem`, `TurnEnd` など）
- `RestoredState` — ログ再生で復元された状態
- `collect_state()` — ログエントリ列から状態を復元する関数
+## Design notes

-### ツール
+A session log records what happened. It is not the current Pod registry and should not be queried as the only source of "what does Pod X mean now?"

- `InspectTool` — Blob 内容を取得する組み込みツール（行範囲・配列スライス・キー指定セレクタ対応）
+Prefer explicit current log variants over broad legacy compatibility when schema changes; hidden compatibility can make future replay bugs silent.
+
+## See also
+
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
+- [`../../docs/design/context-history.md`](../../docs/design/context-history.md)
@@ -0,0 +1,30 @@
+# tools
+
+## Role
+
+`tools` implements built-in tools and shared tool execution helpers used by Pods.
+
+## Boundaries
+
+Owns:
+
+- built-in filesystem, web, memory, and Pod-management tool implementations where applicable
+- bounded tool output formatting
+- scope-aware file operation helpers
+- tool-facing diagnostics suitable for history/model consumption
+
+Does not own:
+
+- manifest permission policy definition (`manifest`)
+- Worker tool-loop semantics (`llm-worker`)
+- Pod lifecycle decisions (`pod`)
+- UI presentation (`tui`)
+
+## Design notes
+
+A tool implementation must assume model input is untrusted. Permission policy, scope checks, output bounding, and redaction are part of the safety boundary, not optional UI behavior.
+
+## See also
+
+- [`../../docs/design/tool-permissions-scope.md`](../../docs/design/tool-permissions-scope.md)
+- [`../../docs/design/memory-knowledge.md`](../../docs/design/memory-knowledge.md)
@@ -1,10 +1,30 @@
 # tui

-Pod と対話するためのターミナル UI クライアント。Unix ソケット経由で Pod に接続し、チャット形式でユーザー入力の送信・アシスタント応答の表示・ツール実行の監視を行う。
+## Role

-## 公開型
+`tui` implements terminal UI clients for interacting with one or more Pods.

- `App` — アプリケーション状態（メッセージ履歴、入力バッファ、スクロール位置）
- `Message` / `MessageKind` — 表示メッセージ（User, Assistant, Tool, Error, Status）
- `PodClient` — Pod との Unix ソケット通信クライアント（`connect()`, `send()`, `next_event()`）
- `draw()` — ratatui によるUI描画関数
+## Boundaries
+
+Owns:
+
+- terminal rendering and input handling
+- local composer state and UI affordances
+- single-Pod attach/restore screens
+- multi-Pod dashboard presentation
+
+Does not own:
+
+- durable transcript authority (`session-store`)
+- Pod current state (`pod-store`)
+- Pod lifecycle policy (`pod`)
+- product CLI ownership (`yoi`)
+
+## Design notes
+
+The TUI should display committed events and Pod snapshots rather than inventing durable state. Local input history and optimistic UI affordances are editing conveniences; they must not become hidden model context.
+
+## See also
+
+- [`../../docs/design/context-history.md`](../../docs/design/context-history.md)
+- [`../../docs/design/pod-session-state.md`](../../docs/design/pod-session-state.md)
@@ -0,0 +1,29 @@
+# workflow
+
+## Role
+
+`workflow` owns project-authored workflow record parsing, validation, and invocation metadata.
+
+## Boundaries
+
+Owns:
+
+- workflow file schema/linting
+- workflow discovery from configured workflow locations
+- typed workflow metadata used by runtime/tooling layers
+
+Does not own:
+
+- generated memory records (`memory`)
+- work item file lifecycle (`tickets.sh`, `work-items/`)
+- Pod orchestration decisions (`pod`, workflows executed by agents)
+- product CLI command shape (`yoi`)
+
+## Design notes
+
+Workflows are curated project assets. They should not be mixed with generated memory, and invoking a workflow should not bypass work item authority or scope policy.
+
+## See also
+
+- [`../../docs/development/workflows.md`](../../docs/development/workflows.md)
+- [`../../docs/design/profiles-manifests-prompts.md`](../../docs/design/profiles-manifests-prompts.md)
@@ -0,0 +1,30 @@
+# yoi
+
+## Role
+
+`yoi` is the product CLI facade. It owns the installed binary name, top-level argument parsing, normal TUI launch, and product subcommands such as `yoi pod` and `yoi memory lint`.
+
+## Boundaries
+
+Owns:
+
+- product command shape and user-facing CLI entry points
+- profile/default selection for ordinary startup
+- wiring library crates into the executable
+- headless maintenance commands that are part of the product surface
+
+Does not own:
+
+- Pod runtime internals (`pod`)
+- socket client mechanics (`client`)
+- model turn orchestration (`llm-worker`)
+- TUI rendering/runtime implementation (`tui`)
+
+## Design notes
+
+Keeping product CLI ownership here prevents lower crates from depending on the binary name or parsing top-level arguments. Runtime launch should use typed command boundaries, not shell-command strings.
+
+## See also
+
+- [`../../docs/design/overview.md`](../../docs/design/overview.md)
+- [`../../docs/design/profiles-manifests-prompts.md`](../../docs/design/profiles-manifests-prompts.md)