tau-coding-agent 0.4.0__tar.gz → 0.4.6__tar.gz

{tau_coding_agent-0.4.0/tau_coding_agent.egg-info → tau_coding_agent-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.4.0
+Version: 0.4.6
 Summary: A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -32,10 +32,10 @@ Dynamic: license-file
 
 # Tau (τ)
 
-A Python reimplementation of [Pi](https://pi.dev), **Tau** brings the same agent framework capabilities to Python developers. A self-extensible agent CLI with a terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools, commands, and customization.
+Inspired by [Pi](https://pi.dev), **Tau** brings the same agent framework capabilities to Python developers. A self-extensible agent CLI with a terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools, commands, and customization.
 
 <p align="center">
-  <img src="assets/tui.png" alt="Tau TUI" width="700">
+  <img src="assets/tui.jpeg" alt="Tau TUI" width="700">
 </p>
 
 Start a conversation with the agent in the terminal.

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/README.md

@@ -1,9 +1,9 @@
 # Tau (τ)
 
-A Python reimplementation of [Pi](https://pi.dev), **Tau** brings the same agent framework capabilities to Python developers. A self-extensible agent CLI with a terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools, commands, and customization.
+Inspired by [Pi](https://pi.dev), **Tau** brings the same agent framework capabilities to Python developers. A self-extensible agent CLI with a terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools, commands, and customization.
 
 <p align="center">
-  <img src="assets/tui.png" alt="Tau TUI" width="700">
+  <img src="assets/tui.jpeg" alt="Tau TUI" width="700">
 </p>
 
 Start a conversation with the agent in the terminal.

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/docs/architecture.md

@@ -70,6 +70,7 @@ User input flows through these stages:
 |--------|---------|
 | `session/` | Session JSONL persistence, compaction, branching |
 | `settings/` | Configuration from JSON files |
+| `resources/` | Unified discovery of extensions, skills, prompts, and themes |
 | `auth/` | Credential storage and resolution |
 | `message/` | Message type definitions |
 | `trust/` | Trust and permission checks |
@@ -97,23 +98,25 @@ User input flows through these stages:
 
 | Module | Purpose |
 |--------|---------|
-| `packages/` | Package/dependency management (reserved) |
+| `packages/` | Installed package and dependency management |
 | `rpc/` | JSON-RPC protocol for IDE integration |
 
 ## Agent Execution State Machine
 
-The agent has three main states:
+The agent has four observable phases:
 
 ```
 IDLE ──user input──> TURN ──no more tool calls──> IDLE
-       ↑                ↓
-       └─ tool results ─┘
+  ├── manual/auto compact ──> COMPACTION ──> previous phase
+  └── tree navigation ──────> BRANCH_SUMMARY ──> IDLE
 ```
 
 | State | Meaning |
 |-------|---------|
 | `IDLE` | No active inference; waiting for user input |
 | `TURN` | Processing a turn: calling inference, executing tools |
+| `COMPACTION` | Generating or applying a context compaction summary |
+| `BRANCH_SUMMARY` | Generating or applying a branch-navigation summary |
 
 The state is exposed via `AgentPhase` enum in `agent/types.py` and accessible to extensions via hooks.
 
@@ -126,14 +129,24 @@ Each agent turn follows this sequence:
 2. Add message to session
 3. Call inference (LLM API)
 4. Collect tool calls from response
-5. Execute tools (in parallel if possible)
+5. Execute tools concurrently only when every call in the batch is marked parallel
 6. Add tool results to context
 7. Call inference again (only if tools were called)
 8. Render all messages and results (TUI)
 9. Save session to disk
-10. Fire completion hooks
+10. Run post-turn compaction and drain messages queued by lifecycle handlers
+11. Fire the settled hook
 ```
 
+TUI overlays participate in focus lifecycle. Hiding or closing a capturing
+overlay restores the next visible overlay or its previous focus target.
+Components exposing `dispose()` are disposed when their overlay closes.
+
+Slash commands declare whether they require an idle agent. Idle-only commands
+are deferred until the current turn settles; UI-only and read-only commands may
+opt into immediate dispatch during a turn. Normal Enter input remains steering,
+and Alt+Enter remains a post-turn follow-up message.
+
 ## Message Types and Context
 
 Messages in sessions are typed:
@@ -204,12 +217,37 @@ Tools are executed in a sandboxed environment:
 6. Result is serialized and added to context
 ```
 
-Built-in tools (bash, read, write, edit, glob, grep, ls) are always available. Custom tools are registered via extensions.
+Built-in tools (bash, read, write, edit, glob, grep, ls) are enabled by default.
+`RuntimeConfig` can allow or exclude tools by name. Custom tools are registered
+via extensions or passed directly to the runtime.
+
+Programmatic runtimes can replace constructed services through
+`RuntimeDependencies`. Typed factories cover settings, LLM/model/auth wiring,
+session storage, hooks, and the tool registry. Session-bound factories run
+again when the active session is replaced.
+
+`Runtime.create_with_result()` returns the initialized runtime together with
+resource diagnostics, extension errors, and requested-versus-selected
+model/provider resolution. `Runtime.create()` remains the convenience API when
+the caller does not need startup details.
+
+Extension reloads pass through a serialized coordinator. Callback-triggered or
+mid-turn requests wait until extension dispatch and the agent lifecycle settle.
+Runtime generations invalidate contexts captured before reload, session
+replacement, or shutdown, and shutdown detaches the extension runtime from its
+hook bus.
 
 ## Extension Points
 
 Tau is designed to be extended without modifying core code. Key extension points via the `tau` parameter in `register()`:
 
+Resource discovery is centralized behind the replaceable `ResourceLoader`
+protocol. `DefaultResourceLoader` supports per-resource overrides. Startup and
+`/reload` consume one `ResourceSnapshot`, keeping extensions, skills, prompts,
+themes, context files, and structured diagnostics consistent. Diagnostics
+identify invalid configured paths, package manifests/resources, hook paths, and
+context read failures without preventing valid resources from loading.
+
 ### Tools
 
 Register custom tools that the agent can call:

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/docs/cli-reference.md

@@ -6,17 +6,21 @@
 tau [OPTIONS] [MESSAGE]
 ```
 
-`MESSAGE` is an optional positional argument. When provided with `--print` or `--mode print`, it is the prompt to run.
+Use `--prompt TEXT` for a non-interactive prompt. Piped stdin can supply or
+augment it.
 
 ## Options
 
 | Option | Short | Description |
 |--------|-------|-------------|
-| `--provider` | `-p` | Provider to use, e.g. `anthropic`, `openai`, `groq` |
-| `--model` | `-m` | Model ID, or `provider/model` shorthand (e.g. `groq/llama-3.3-70b-versatile`) |
+| `--prompt` | `-p` | Run a non-interactive prompt |
+| `--provider` | | Provider to use, e.g. `anthropic`, `openai`, `groq` |
+| `--model` | | Model ID, or `provider/model` shorthand (e.g. `groq/llama-3.3-70b-versatile`) |
 | `--theme` | `-t` | UI theme: `default`, `dracula`, `nord`, `gruvbox`, `catppuccin`, `ayu-dark`, `everforest`, `horizon`, `kanagawa`, `material-ocean`, `monokai`, `night-owl`, `one-dark`, `rose-pine`, `solarized-dark`, `tokyo-night`, or a custom name |
-| `--resume` | `-r` | Resume the most recent session |
-| `--session` | `-s` | Resume a specific session by ID or file path |
+| `--resume [ID]` | `-r` | Resume the most recent or a specified session |
+| `--fork ID` | | Fork a specified session at startup |
+| `--session-dir PATH` | | Override session storage |
+| `--name NAME` | | Set the session display name at startup |
 | `--ephemeral` | `-e` | Don't save this session to disk |
 | `--approve` | `-a` | Trust project-local files (extensions, settings, context files) for this run |
 | `--no-approve` | `-na` | Don't trust project-local files for this run |
@@ -42,10 +46,14 @@ tau --model claude-sonnet-4-6
 Run a single prompt, print the response, and exit:
 
 ```bash
-tau --print "Summarize this repo"
-tau -p anthropic --print "What is this file?" 
+tau --prompt "Summarize this repo"
+cat README.md | tau --print --prompt "Summarize this text"
+tau --prompt "Compare these files" @src/old.py @src/new.py
 ```
 
+Piped text, attached file contents, and the explicit prompt are combined in
+that order.
+
 ### JSON mode
 
 Emit a JSON event stream on stdout:

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/docs/extensions.md

@@ -3,6 +3,12 @@
 Extensions are plain Python files that hook into tau's lifecycle. Each one exports
 a single `register(tau)` function — everything is wired up there.
 
+Extension tools and commands may shadow built-ins while loaded. Tau retains the
+shadowed source layer, so disabling or reloading the extension restores the
+previous implementation. Reload also replaces extension message renderers,
+autocomplete providers, shortcuts, and published services; do not retain
+service objects across reload.
+
 ## File locations
 
 tau loads extensions from three sources, in this order:
@@ -36,6 +42,41 @@ dependencies with incompatible versions. The install only runs once — a hash o
 the dependency list is cached, so unchanged manifests are a no-op on subsequent
 launches.
 
+## Installable resource packages
+
+`tau install` accepts PyPI names, pip-compatible Git URLs, local distributions,
+and direct wheel or source-archive URLs:
+
+```bash
+tau install pypi:tau-tools==1.2.3
+tau install git+ssh://git@github.com/example/tau-tools.git@v1
+tau install ./dist/tau_tools-1.2.3-py3-none-any.whl
+tau install https://packages.example.com/tau_tools-1.2.3-py3-none-any.whl
+tau install tau-tools==1.2.3 --index-url https://packages.example.com/simple
+```
+
+Repeat `--extra-index-url URL` to resolve dependencies from additional indexes.
+Index configuration is retained for future updates.
+
+Packages can bundle extensions, skills, prompts, and themes:
+
+```json
+{
+  "tau": {
+    "extensions": ["extensions/main.py"],
+    "skills": ["skills"],
+    "prompts": ["prompts"],
+    "themes": ["themes"]
+  }
+}
+```
+
+Conventional resource directories are discovered when a manifest field is
+omitted. Package entries in `settings.json` support an `enabled` switch and
+optional `extensions`, `skills`, `prompts`, and `themes` path filters. An empty
+filter disables that resource type. Use `tau update --all` to update Tau and
+all installed packages.
+
 ## Entry point
 
 Every extension must export a `register(tau)` function:
@@ -48,6 +89,34 @@ def register(tau):
     pass
 ```
 
+### Inline extension factories
+
+Python API users can supply the same registration function directly through
+`RuntimeConfig`, without creating or installing an extension file:
+
+```python
+from tau.extensions import ExtensionAPI
+from tau.runtime.types import RuntimeConfig
+
+def configure(tau: ExtensionAPI) -> None:
+    tau.register_tool(MyTool())
+    tau.append_prompt("Use the embedding application's workflow.")
+
+config = RuntimeConfig(
+    cwd=Path.cwd(),
+    extension_factories=[configure],
+)
+```
+
+Inline factories receive the normal `ExtensionAPI`, can be synchronous or
+asynchronous, and load after file-based extensions. They participate in the
+same tool, command, hook, provider, service, prompt, theme, and UI registration
+systems. Factory failures are isolated and reported as `ExtensionError`.
+
+`/reload` unloads the old inline extensions and executes the factories again,
+preventing duplicate hook subscriptions. Session replacement reuses the active
+extension runtime and does not rerun factories.
+
 `register` may be `async` if setup requires awaiting:
 
 ```python
@@ -212,9 +281,17 @@ def register(tau):
 
 #### Agent state
 
+| Property | Type | Description |
+|----------|------|-------------|
+| `ctx.phase` | `AgentPhase` | Current lifecycle phase: `idle`, `turn`, `compaction`, or `branch_summary` |
+| `ctx.streaming_message` | `AssistantMessage \| None` | Current partial assistant response |
+| `ctx.pending_tool_call_ids` | `frozenset[str]` | Snapshot of tool calls that have started but not finished |
+| `ctx.error_message` | `str \| None` | Most recent engine error |
+| `ctx.queued_messages` | `dict[str, list[LLMMessage]]` | Snapshots of the steering and follow-up queues |
+
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `ctx.is_idle()` | `bool` | `True` when the agent is not currently streaming a response |
+| `ctx.is_idle()` | `bool` | `True` when `ctx.phase` is `AgentPhase.IDLE` |
 | `ctx.abort()` | — | Cancel the current agent turn; no-op if already idle |
 | `ctx.shutdown()` | — | Exit tau gracefully |
 | `ctx.get_context_usage()` | `dict \| None` | Token usage info (see below) |
@@ -224,6 +301,13 @@ def register(tau):
 | `ctx.signal` | `asyncio.Event \| None` | The current abort signal while the agent is streaming; the event is set when the turn is aborted. `None` when idle |
 | `ctx.get_system_prompt_options()` | `dict` | Metadata about how the active system prompt was assembled — keys: `skills`, `prompts`, `tools`, `system_prompt_length` |
 
+Extensions can inject a user message with
+`await ctx.send_user_message(content, deliver_as="steer", trigger_turn=False)`.
+Set `trigger_turn=True` to start a new turn immediately when the agent is idle;
+while it is busy, the message is queued using the selected delivery mode. In
+interactive mode, an immediately triggered message is rendered as a normal user
+message before the assistant response.
+
 `get_context_usage()` returns a dict with three keys, or `None` if token data is not yet available (e.g. immediately after compaction, before the next LLM response):
 
 ```python
@@ -251,7 +335,7 @@ These methods are `async` and are available in both event handlers and command h
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `await ctx.wait_for_idle()` | — | Suspend until the agent finishes its current turn |
+| `await ctx.wait_for_idle()` | — | Suspend until the active invocation and its post-run save/compaction processing finish |
 | `await ctx.new_session()` | `{"cancelled": bool}` | Start a fresh session |
 | `await ctx.fork(entry_id)` | `{"cancelled": bool}` | Fork from a specific session entry |
 | `await ctx.navigate_tree(target_id, summarize=False, custom_instructions=None)` | `{"cancelled": bool}` | Jump to another branch in the session tree |
@@ -297,12 +381,30 @@ async def cmd(ctx, args):
     ctx.compact(custom_instructions="Keep only the final conclusions.")
 ```
 
-`navigate_tree` optionally generates a branch summary before switching:
+`navigate_tree` optionally generates a branch summary and attaches it to the
+destination branch. If summary generation fails, navigation still completes
+without a summary:
 
 ```python
 result = await ctx.navigate_tree(target_id, summarize=True)
 ```
 
+Extensions can replace the default branch-summary model call:
+
+```python
+from tau.hooks import SessionBeforeTreeResult
+
+def register(tau):
+    @tau.on("session_before_tree")
+    async def summarize(event, ctx):
+        entries = event.preparation.entries_to_summarize
+        summary = await my_summarizer(entries)
+        return SessionBeforeTreeResult(
+            summary=summary,
+            summary_details={"source": "my-extension"},
+        )
+```
+
 #### `branch_entries` vs `session_entries`
 
 The session file stores entries from every branch ever taken — forks, navigations, abandoned paths. `session_entries` returns all of them. `branch_entries` returns only the linear path from the root to the current leaf — the entries actually in scope for the current conversation.
@@ -359,7 +461,11 @@ def register(tau):
 | `session_shutdown` | `reason`, `target_session_file` | — | Session about to close — last chance for cleanup |
 | `session_before_switch` | `reason`, `target_session_file` | `SessionBeforeSwitchResult` | About to replace the active session — return `cancel=True` to block |
 | `session_before_fork` | `entry_id`, `position` | `SessionBeforeForkResult` | About to create a branch — return `cancel=True` to block |
-| `session_before_tree` | `preparation` | `SessionBeforeTreeResult` | About to rewrite the session tree (branch navigation). Mutate `preparation` or return `cancel=True` |
+| `session_before_tree` | `preparation` | `SessionBeforeTreeResult` | About to rewrite the tree. Return `summary=` and optional `summary_details=` to replace default summarization, or `cancel=True` to block |
+| `branch_summary_start` | `old_leaf_id`, `target_id`, `from_extension` | — | Branch summarization begins |
+| `branch_summary_end` | `old_leaf_id`, `target_id`, `summary_entry_id`, `summary_length`, `from_extension` | — | Summary attached to the destination |
+| `branch_summary_failure` | `old_leaf_id`, `target_id`, `error` | — | Summary failed; navigation continues without it |
+| `branch_summary_cancelled` | `old_leaf_id`, `target_id`, `reason` | — | Summary or navigation was cancelled |
 | `session_tree` | `new_leaf_id`, `old_leaf_id`, `from_extension` | — | Session tree has been rewritten with the new active leaf |
 
 **Agent & turn lifecycle**
@@ -372,7 +478,7 @@ def register(tau):
 | `agent_error` | `error` | — | Engine terminated with an unrecoverable error |
 | `turn_start` | `turn_index`, `timestamp` | — | New LLM inference turn begins |
 | `turn_end` | `turn_index`, `message`, `tool_results` | — | Turn completes with assistant message and tool results |
-| `settled` | — | — | Agent finishes a `prompt()` call with no more queued turns — the agent is fully idle |
+| `settled` | — | — | The invocation completed queued turns and post-run compaction with no messages currently queued; this is an observation, not a lock against concurrent submissions |
 
 **Input**
 
@@ -425,9 +531,11 @@ def register(tau):
 
 | Event | Payload fields | Result type | Description |
 |-------|---------------|-------------|-------------|
-| `before_compaction` | `preparation`, `entries`, `manual` | `BeforeCompactionResult` | Before the LLM summarisation call — see [Custom Compaction](#custom-compaction) |
-| `compaction_start` | `manual` | — | Compaction begins (after `before_compaction` passes) |
-| `compaction_end` | `manual`, `tokens_before`, `summary_length`, `from_extension` | — | Compaction finished |
+| `before_compaction` | `preparation`, `entries`, `manual`, `reason`, `will_retry` | `BeforeCompactionResult` | Before summarization; may cancel or provide a complete compaction |
+| `compaction_start` | `manual`, `reason`, `will_retry` | — | Compaction begins after interception |
+| `compaction_end` | `manual`, `reason`, `will_retry`, `tokens_before`, `summary_length`, `from_extension` | — | Compaction succeeds |
+| `compaction_failure` | `manual`, `reason`, `will_retry`, `error` | — | Compaction fails |
+| `compaction_cancelled` | `manual`, `reason`, `will_retry` | — | An extension cancels compaction |
 
 **Model & settings**
 
@@ -706,7 +814,7 @@ def register(tau):
 | Method | Description |
 |--------|-------------|
 | `tau.register_tool(tool)` | Add a tool the agent can call |
-| `tau.register_command(name, desc, handler, aliases=[], get_argument_completions=None)` | Add a `/name` slash command with optional argument tab-completion |
+| `tau.register_command(name, desc, handler, aliases=[], get_argument_completions=None, argument_hint=None, requires_idle=True)` | Add a `/name` slash command; set `requires_idle=False` only for UI-only or read-only handlers safe during an active turn |
 | `tau.on(event, handler)` / `@tau.on(event)` | Subscribe to a lifecycle event |
 | `tau.register_shortcut(key, desc, handler)` | Bind a keyboard shortcut |
 | `tau.append_prompt(text)` | Append text to the system prompt |
@@ -1343,6 +1451,18 @@ async def on_start(event, ctx):
 `/reload` re-discovers and hot-reloads all extensions, skills, prompts, and
 settings without restarting the session.
 
+Reload requests are serialized. A request made from an extension callback or
+while the agent is processing is queued until the callback pipeline and complete
+agent lifecycle settle. Multiple queued requests are coalesced. Consequently,
+`await ctx.reload()` acknowledges a request but does not guarantee that a
+deferred reload has already completed.
+
+Contexts are generation-bound. An `ExtensionContext` captured before `/reload`,
+`/new`, `/resume`, `/clone`, or runtime shutdown raises
+`StaleExtensionContextError` when reused. Do not retain contexts in long-lived
+background tasks; capture immutable values or acquire a fresh context from a
+new callback.
+
 **What gets picked up:**
 - New or modified extension files
 - New or modified skill and prompt template files
@@ -1352,10 +1472,16 @@ settings without restarting the session.
 **What persists across reload:**
 - The current session (messages, branching state)
 - Auth credentials
-- Any runtime state your extension stored outside its module (e.g. in a global variable — module globals are re-created on reload)
+- Normally imported third-party Python modules, which remain cached in `sys.modules`
+- External state not explicitly released by the extension
 
 **What resets:**
 - All registered tools, commands, shortcuts, and event handlers — re-registered from scratch
 - The system prompt — rebuilt from SYSTEM.md and all `append_prompt` calls
+- Extension entry-module globals and inline factory state
+
+Tau emits `extension_unload` before replacing an extension runtime and
+`runtime_stop` before shutdown. Use those events to release subprocesses,
+background tasks, sockets, and registrations outside Tau.
 
 After reload, new tools are available to the model immediately in the next turn.

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/docs/keybindings.md

@@ -13,7 +13,7 @@
 | Ctrl+K | Kill to end of line |
 | Ctrl+W | Delete previous word |
 | Ctrl+A / Home | Move to line start |
-| Ctrl+E / End | Move to line end |
+| Ctrl+E / End | Move to line end (Ctrl+E falls through to the app when input is empty) |
 | Delete / Ctrl+D | Delete character at cursor |
 
 ### Message Queue
@@ -30,7 +30,8 @@
 | Escape | Abort current turn; restore queued messages |
 | Ctrl+C | Abort turn; double-press to quit |
 | Ctrl+D | Quit (on empty input) |
-| Ctrl+O | Toggle expand/collapse for template blocks |
+| Ctrl+O | Toggle expand/collapse for thinking and tool-result blocks |
+| Ctrl+E | Toggle template and skill blocks when the editor is empty |
 
 ### Pickers (model, theme, command palette)
 
@@ -52,12 +53,14 @@
 Pass a `KeyMap` to `App.create()` at startup:
 
 ```python
-from tau.tui.keybindings import KeyMap
+from tau.tui import KeyMap
 
 overrides: KeyMap = {
     "tui.app.quit": ["ctrl+q"],
     "tui.input.submit": ["enter"],
     "app.message.followup": ["alt+enter"],
+    "app.details.toggle": ["ctrl+o"],
+    "app.invocations.toggle": ["ctrl+e"],
 }
 
 app = await App.create(runtime, keybindings=overrides)
@@ -75,6 +78,8 @@ A `KeyMap` is `dict[str, list[str]]` — action name → list of key combos that
 | `tui.input.word_back` | `ctrl+w` | Delete previous word |
 | `app.message.followup` | `alt+enter` | Queue as follow-up message |
 | `app.message.dequeue` | `alt+up` | Restore queued messages into editor |
+| `app.details.toggle` | `ctrl+o` | Toggle thinking and tool-result previews |
+| `app.invocations.toggle` | `ctrl+e` | Toggle template and skill blocks |
 | `tui.app.quit` | `ctrl+c`, `ctrl+d` | Quit tau |
 | `tui.app.abort` | `ctrl+c` | Abort the current turn |
 | `tui.select.up` | `up`, `ctrl+p` | Move selection up |

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/docs/messages.md

@@ -28,6 +28,12 @@ Referenced files are automatically processed based on type:
 
 A response from the LLM. Can include text and tool calls.
 
+Assistant messages also store provider usage metadata: input, output,
+cache-read, and cache-write token counts. The
+`input_tokens_include_cache_read` flag records whether cached tokens are
+already included in the provider's input count, preventing context usage from
+counting the same tokens twice.
+
 ```python
 {
   "type": "assistant",

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.6}/docs/project-structure.md

@@ -1,11 +1,11 @@
 # Project Structure
 
-Tau consists of 205 Python modules organized into 22 main packages. This page documents the codebase organization and provides module-by-module reference for contributors and agents.
+Tau consists of 230 Python modules organized into 25 main packages. This page documents the codebase organization and provides module-by-module reference for contributors and agents.
 
 ## Directory Structure
 
 ```
-tau/                                # Main package (205 modules)
+tau/                                # Main package (230 modules)
 ├── __init__.py
 ├── content_registry.py             # Content registry abstractions
 ├── agent/                          # Agent execution service
@@ -31,6 +31,7 @@ tau/                                # Main package (205 modules)
 ├── message/                        # Message types and utilities
 ├── packages/                       # Package/dependency management
 ├── prompts/                        # Prompt template system
+├── resources/                      # Unified runtime resource discovery
 ├── rpc/                            # JSON-RPC protocol for IDE integration
 ├── runtime/                        # Agent runtime service
 ├── session/                        # Session management and persistence
@@ -154,12 +155,22 @@ Message data structures and utilities.
 
 ### `packages/` - Package Management
 
-Package/dependency resolution (reserved for future use).
+Installed package and dependency management.
 
 - `manager.py` - Package management
 - `types.py` - Package types
 - `utils.py` - Package utilities
 
+### `resources/` - Resource Discovery
+
+The replaceable loader builds one immutable snapshot from built-in, global,
+project, installed-package, hook-provided, and context-file resources. It
+supports focused overrides and structured diagnostics. Runtime startup and
+`/reload` both consume it.
+
+- `loader.py` - Resource loader protocol, default discovery, and registry application
+- `types.py` - `ResourceContext`, immutable `ResourceSnapshot`, context files, and diagnostics
+
 ### `prompts/` - Prompt Template System
 
 Prompt loading and variable substitution.
@@ -178,10 +189,12 @@ JSON-RPC server for IDE integration.
 
 ### `runtime/` - Agent Runtime
 
-Wires together agent, session, engine, and extensions.
+Wires together agent, session, engine, and extensions with replaceable service
+factories for programmatic embedding.
 
+- `dependencies.py` - Typed dependency factories and creation contexts
 - `service.py` - Main runtime orchestration
-- `types.py` - Runtime state types
+- `types.py` - Runtime state, configuration, and structured startup result types
 
 ### `session/` - Session Management
 
@@ -234,35 +247,33 @@ Trust and permission system for tool execution.
 - `types.py` - Trust data structures
 - `utils.py` - Trust utilities
 
-### `tui/` - Terminal User Interface
-
-Complete terminal UI (22 modules, 736 LOC).
-
-Core components:
-- `tui.py` - Main TUI event loop
-- `app.py` - TUI application state
-- `terminal.py` - Terminal control and cursor management
-- `renderer.py` - Differential update renderer
-
-Input handling:
-- `input.py` - Text input editor
-- `input_handler.py` - Input event handling
-- `autocomplete.py` - Command/file autocomplete
-- `component.py` - UI component system
-
-Rendering:
-- `message_renderers.py` - Message and tool result rendering
-- `markdown.py` - Markdown to ANSI rendering
-- `overlay.py` - Overlay UI (dialogs, popups)
-
-Display:
-- `theme.py` - Theme application
-- `ansi.py` - ANSI code utilities
-- `keybindings.py` - Keybinding definitions
-- `fuzzy.py` - Fuzzy matching for search
-
-Integration:
-- `agent_hooks.py` - TUI event hooks
+### `tui/` - Terminal UI Primitives
+
+Reusable terminal parsing, differential rendering, components, themes, and
+keybindings.
+
+- `tui.py` - Main event loop, focus, overlays, and differential rendering
+- `terminal.py` - Terminal control and capability detection
+- `input.py` - Generic input events, terminal parser, and keybinding registry
+- `component.py` - Component and container primitives
+- `components/` - Editor, text input, selectors, spinner, images, and boxes
+- `autocomplete.py` - Generic autocomplete management
+- `markdown.py` - Markdown-to-ANSI rendering
+- `theme.py` - TUI theme types
+- `ui_context.py` - Extension-facing UI context
+
+### `modes/interactive/` - Interactive Application
+
+Interactive runtime orchestration and Tau-specific UI composition.
+
+- `app.py` - Application lifecycle and global shortcuts
+- `agent_hooks.py` - Agent-event to UI-state projection
+- `input_handler.py` - Runtime-aware submit, queue, media, and history orchestration
+- `commands/` - Interactive slash-command implementations
+- `components/layout.py` - Editor-zone composition
+- `components/message_list.py` - Message and tool-result rendering
+- `components/selector_controller.py` - Inline selector lifecycle and input routing
+- `components/overlays.py` - Interactive dialogs and editors
 - `ui_context.py` - UI state context
 
 ## Key Types and Classes
@@ -402,7 +413,7 @@ See [Extensions Guide](extensions.md) for detailed examples.
 ## Code Statistics
 
 - **Total modules**: 205 Python files
-- **Main package**: tau/ (22 subpackages)
+- **Main package**: tau/ (25 subpackages)
 - **Test coverage**: tests/ directory
 - **Lines of code**: ~8,000 LOC (excluding tests and docs)
 - **Type hints**: Full type coverage with mypy/pyright