@shanepadgett/tau-agent 0.18.0 → 0.18.1

package/README.md

@@ -25,6 +25,7 @@ pi -e .
 
 ## Docs
 
+- [Context management](./docs/context.md) — repository context structure and taxonomy
 - [Extending Tau Agent](./docs/extending-tau-agent.md) — public events and integration
 - [Subagents](./docs/subagents.md) — custom agent definitions
 - [TUI](./docs/tui.md) — shared UI components

package/docs/context.md

@@ -0,0 +1,62 @@
+# Context management
+
+Tau uses `.pi/contexts` as a reusable map of the repository. A selected context gives an agent the primary files for a work scope and points it toward related files without loading everything.
+
+## Structure
+
+The catalog has three levels:
+
+```text
+.pi/contexts/<domain>/<concept>.toml
+                         └── [entry]
+```
+
+- **Domain**: a stable top-level area of the repository, such as `commerce`, `platform`, or `documentation`. Domains become tabs in `/context`.
+- **Concept**: a coherent subsystem or capability inside a domain. Each concept is one TOML file.
+- **Entry**: a selectable work scope inside that concept. Each TOML section defines one entry.
+
+Domain folders, concept filenames, and entry section names use lowercase kebab-case.
+
+```toml
+name = "Checkout"
+description = "Checkout calculation and order submission"
+
+[orchestration]
+description = "Building and submitting a checkout order"
+files = ["src/checkout/order.ts", "src/checkout/service.ts"]
+anchors = ["test/checkout/service.test.ts", "src/payments/client.ts"]
+
+[discounts]
+description = "Applying coupons and account discounts"
+files = ["src/checkout/discounts.ts"]
+anchors = ["test/checkout/discounts.test.ts"]
+```
+
+Saved as `.pi/contexts/commerce/checkout.toml`, these entries have the IDs `commerce/checkout/orchestration` and `commerce/checkout/discounts`.
+
+## Build a useful taxonomy
+
+A good entry gives the agent enough primary code to start one recurring kind of work without flooding its context window. Classify each scope from the top down:
+
+1. **Domain:** Which stable product or technical area owns this work?
+2. **Concept:** Which subsystem inside that area has a clear shared purpose?
+3. **Entry:** Which files are commonly needed together for one task?
+
+Reuse existing terms when they still describe the code honestly. Create, move, split, or merge taxonomy when ownership or subsystem boundaries change. Directory layout can inform the decision, though domains and concepts should describe responsibility rather than copy the source tree.
+
+Keep entries focused. Names such as `misc`, `shared`, and `other` hide missing boundaries. A broad `all` entry can support deliberate subsystem-wide work, but focused entries should remain available for normal tasks. If an entry keeps collecting unrelated paths, split it by work scope. If several tiny entries are always selected together, merge them.
+
+Catalog durable code, configuration, tests, standards, and long-lived documentation. Leave scratch files, working plans, interviews, generated output, and rough ideas out of the catalog.
+
+## Choose files and anchors
+
+- `files` are eagerly read when the entry is selected. Include primary files that are usually required for that scope.
+- `anchors` are shown to the agent as unloaded navigation paths. Use them for related tests, callers, shared dependencies, or documentation that is useful only for some tasks.
+
+Keep the eager set small enough to read on every selection. Keep each path's loading class consistent across the catalog. If selected entries classify the same path differently, eager loading wins.
+
+## Maintain the map
+
+Inspect the existing catalog before placing new paths. Re-evaluate domain, concept, and entry boundaries after moves, ownership changes, or a coherent batch of new work; avoid stuffing paths into the nearest existing bucket.
+
+Run `/context-sync` to update the catalog from uncommitted repository changes. Tau can also delegate to the `context-sync` subagent when automation is enabled. Context sync checks every eligible changed file for membership, removes stale paths, and re-evaluates the taxonomy before editing `.pi/contexts`.

package/extensions/context/README.md

@@ -2,6 +2,8 @@
 
 Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
 
+See [Context management](../../docs/context.md) for catalog structure and taxonomy guidance.
+
 Use `/context` to select entries. Entry `files` are injected through Tau autoread. Entry `anchors` supply lazy navigation paths that the agent can grep or read in ranges when needed.
 
 After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Context sync catalogs durable code and long-lived documentation. Scratch pads, working plans, interviews, rough ideas, and other temporary artifacts should stay out; add recurring transient paths to `validation.ignoreGlobs`. Humans can also run `/context-sync` or `/context-sync <nudge>` and press Escape to cancel a running sync. It walks domain → concept → entry → membership, edits only `.pi/contexts` with `patch`, and the harness verifies write scope plus catalog invariants afterward. Out-of-scope writes are restored and the run fails. Optional nudge text soft-steers judgment without skipping evidence.

package/extensions/tau-help/index.ts

@@ -7,7 +7,7 @@ import { Markdown, type Component, visibleWidth } from "@earendil-works/pi-tui";
 const TAU_DOCS_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs");
 const TAU_DOCS_GUIDANCE = `Tau Agent documentation (read only when the user asks about Tau Agent, Rok, Tau extensions, Tau event APIs, harness behavior, or extending Tau Agent):
 - Tau Agent docs: ${TAU_DOCS_PATH}
-- When asked about: public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
+- When asked about: context management / .pi/contexts taxonomy (docs/context.md), public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
 - Resolve Tau docs/... under Tau Agent docs, not the current working directory
 - When working on Tau topics, read the docs and follow .md cross-references before implementing
 - Do not read Tau Agent docs for normal coding tasks`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.18.0",
+	"version": "0.18.1",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.18.0",
+		"@shanepadgett/tau-tui": "0.18.1",
 		"@toon-format/toon": "2.3.0",
 		"smol-toml": "1.7.0"
 	},