refactor: clean context tree architecture for v0.2.2

Author: ZEDIUM-Off

AGENTS.md

@@ -80,7 +80,7 @@ Behavior implemented:
 - `agent:start`: pathless hook selected by scope when prompt references paths such as `@src/index.ts`.
 - `tool:read`: appends context bundle to read tool results.
 - `tool:edit` / `tool:write`: preflight injects context once, blocks initial mutation, then allows retry.
-- `session:spawn`: used by `/ct-new <path> [prompt]`.
+- `session:spawn`: schema/config concept for future config-driven session workflows; no slash command currently consumes it.
 - `subagent:spawn`: schema/config concept; runner interop still planned.
 
 ## Design principles
@@ -119,7 +119,6 @@ Implemented commands:
 /ct-cache-list
 /ct-cache-refresh <path>
 /ct-tui on|off
-/ct-new <path> [prompt]
 /ct-subagent <path> <task>
 ```
 

CHANGELOG.md

@@ -6,6 +6,22 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-04-30
+
+### Added
+
+- Added user-global Context Tree config loading from `~/.pi/CONTEXT.json`, with `PI_CONTEXT_TREE_GLOBAL` override for tests and custom setups.
+
+### Changed
+
+- Cleaned up the code architecture by splitting runtime, command, bundle, TUI, and init-wizard responsibilities into focused modules.
+- Split `/ct-*` command registration into dedicated command groups for status, explain, cache, upgrade, init, and subagent concerns.
+- Updated public documentation to reflect the current architecture and command surface.
+
+### Removed
+
+- Removed `/ct-new`; session workflows are now left to Context Tree configuration and future config-driven integrations.
+
 ## [0.2.1] - 2026-04-29
 
 ### Added
@@ -66,7 +82,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 - Synced `pnpm-lock.yaml` for reproducible installs.
 
-[Unreleased]: https://github.com/ZEDIUM-Off/pi-context-tree/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/ZEDIUM-Off/pi-context-tree/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/ZEDIUM-Off/pi-context-tree/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/ZEDIUM-Off/pi-context-tree/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/ZEDIUM-Off/pi-context-tree/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/ZEDIUM-Off/pi-context-tree/releases/tag/v0.1.0

CONTEXT.json

@@ -70,26 +70,16 @@
 		},
 		{
 			"on": "agent:start",
-			"inject": [
-				"./src/context-schema.ts"
-			]
+			"inject": ["./src/context-schema.ts"]
 		},
 		{
 			"on": "tool:read",
-			"match": [
-				"CONTEXT.json",
-				"**/CONTEXT.json"
-			],
-			"inject": [
-				"./src/context-schema.ts"
-			]
+			"match": ["CONTEXT.json", "**/CONTEXT.json"],
+			"inject": ["./src/context-schema.ts"]
 		},
 		{
 			"on": "tool:edit",
-			"match": [
-				"CONTEXT.json",
-				"**/CONTEXT.json"
-			],
+			"match": ["CONTEXT.json", "**/CONTEXT.json"],
 			"inject": [
 				{
 					"type": "file",
@@ -104,10 +94,7 @@
 		},
 		{
 			"on": "tool:write",
-			"match": [
-				"CONTEXT.json",
-				"**/CONTEXT.json"
-			],
+			"match": ["CONTEXT.json", "**/CONTEXT.json"],
 			"inject": [
 				{
 					"type": "file",

CONTRIBUTING.md

@@ -141,17 +141,18 @@ src/match.ts           glob/operation matching
 src/normalize.ts       inject/default normalization
 src/extract.ts         section/line/marker extraction
 src/cache.ts           URL cache
-src/bundle.ts          bundle build/render/hash
+src/bundle.ts          compatibility facade for bundle exports
+src/bundle/            explain/build/render/stability modules
 src/permissions.ts     scope guard decisions
-src/tui.ts             status/widget rendering
-src/sessions.ts        scoped session command helpers
-src/subagents.ts       pi-subagents interop
-src/commands.ts        slash command handlers
-src/hooks.ts           Pi event hooks
+src/tui.ts             compatibility facade for TUI exports
+src/tui/               status/widget/detail rendering and summaries
+src/runtime/           Pi lifecycle and tool hooks
+src/commands/          slash command groups
+src/subagents.ts       pi-subagents interop placeholder
 src/index.ts           extension composition only
 ```
 
-Current code is not fully split yet; see `docs/architecture-review.md`.
+The runtime is split into focused modules; see `docs/architecture-review.md` for current boundaries and planned integration points.
 
 ## Pull request checklist
 

README.md

@@ -14,7 +14,7 @@ hook + optional target path
 → matching hooks[] entries
 → mode-specific inline excerpts or references
 → bounded context bundle
-→ Pi turn, read result, edit preflight, or scoped session
+→ Pi turn, read result, or edit preflight
 ```
 
 ## Current status
@@ -27,13 +27,13 @@ Implemented MVP:
 - hook/match compatibility validation: path-aware hooks require `match[]`, pathless hooks forbid it;
 - hooks: `session:start`, `agent:start`, `tool:*`, `session:spawn`, `subagent:spawn`;
 - file and URL inject sources;
+- user-global injection config via `~/.pi/CONTEXT.json` or `PI_CONTEXT_TREE_GLOBAL`;
 - URL cache under `.pi/context-tree/cache/urls`;
 - markdown section extraction, line ranges, markers, and annotated segments;
 - bundle hashing and dedupe;
 - read-result context injection;
 - edit/write preflight injection;
 - self-read skip to avoid reinjecting the file being read;
-- scoped session command;
 - scope guard fallback;
 - structured TUI status/widget;
 - unit tests for schema, matching, extraction, cache, bundles, permissions.
@@ -46,7 +46,7 @@ Minimal example:
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/ZEDIUM-Off/pi-context-tree/v0.2.0/schemas/context.schema.json",
+  "$schema": "https://raw.githubusercontent.com/ZEDIUM-Off/pi-context-tree/v0.2.2/schemas/context.schema.json",
   "hooks": [
     {
       "on": "tool:read",
@@ -103,7 +103,6 @@ See [`docs/schema.md`](docs/schema.md) for full schema field behavior and best p
 /ct-tui on|off             toggle Context Tree widget display only
 /ct-init [--resume]        initialize editable Context Tree config for current codebase
 /ct-init-review <proposal> review agent proposal inside current init flow
-/ct-new <path> [prompt]    create new Pi session seeded with session:spawn bundle
 /ct-subagent <path> <task> planned subagent handoff via subagent:spawn
 ```
 
@@ -146,6 +145,16 @@ Disable extension runtime:
 /ct-toggle off
 ```
 
+## Global config
+
+Context Tree also loads an optional user-global config before project scopes:
+
+```text
+~/.pi/CONTEXT.json
+```
+
+Set `PI_CONTEXT_TREE_GLOBAL=/path/to/CONTEXT.json` to override the location. File sources in the global config resolve relative to the global config file; path-aware matches are evaluated against repository-relative target paths.
+
 ## Changelog
 
 Release notes live in [`CHANGELOG.md`](CHANGELOG.md). GitHub releases mirror the same version sections.
@@ -219,7 +228,7 @@ For a Git URL, this clones or fast-forwards the target repository under `.test-w
 
 This repo uses Context Tree to develop itself:
 
-- root `CONTEXT.json` injects README only for scoped session context;
+- root `CONTEXT.json` injects README and package metadata at session startup;
 - `src/CONTEXT.json` injects Pi docs for extension runtime files and implementation-plan sections for core files;
 - `scripts/CONTEXT.json` injects the canonical schema for schema generation;
 - `test/CONTEXT.json` injects test strategy sections.

docs/architecture-review.md

@@ -9,13 +9,18 @@ Current implementation works, but several responsibilities still live together i
 ## Current state
 
 ```text
-src/context-schema.ts   schema and inferred TS types
-src/context-tree.ts     scan, match, normalize, extraction, URL cache, bundle rendering
+src/context-schema.ts   explicit schema compatibility exports
+src/context-tree.ts     explicit public API compatibility exports
+src/public-api.ts       curated public API surface
+src/runtime/            Pi extension lifecycle and tool hooks
+src/commands/           slash command registration and handlers
+src/bundle/             explain/build/render/stability bundle modules
+src/tui/                TUI state summaries, widgets, detail panel, formatting
+src/init/               init wizard phase machine, prompts, submit/review flow
 src/permissions.ts      scope guard decision logic
-src/index.ts            Pi extension hooks, commands, TUI state, session command
 ```
 
-This is acceptable for MVP, but `context-tree.ts` and `index.ts` are too broad for long-term maintenance.
+The large legacy entrypoints have been split. `context-tree.ts` is now a compatibility facade over the curated `public-api.ts` surface rather than a broad export of internals.
 
 ## Target architecture
 
@@ -39,25 +44,34 @@ src/cache.ts
   URL cache keying, TTL, stale fallback, metadata read/write.
 
 src/bundle.ts
-  Load sources, apply self-read skip, build bundle hash, render bundle markdown.
+  Compatibility facade for public bundle exports.
+
+src/bundle/
+  Explain hooks, load sources, apply self-read skip, build bundle hash, render bundle markdown.
 
 src/permissions.ts
   Pure scope guard decision engine.
 
 src/tui.ts
-  TUI state, compact widget rendering, status rendering, on-demand detail text.
+  Compatibility facade for public TUI exports.
 
-src/sessions.ts
-  /context-tree new helpers, custom session entries/messages.
+src/tui/
+  TUI state, compact widget rendering, status rendering, on-demand detail text.
 
 src/subagents.ts
-  Resolve subagent_spawn context and interop with pi-subagents.
+  Resolve subagent:spawn context and interop with pi-subagents.
+
+src/commands/register.ts
+  Slash command composition only.
+
+src/commands/*-commands.ts
+  Slash command handlers grouped by status, explain, cache, upgrade, init, and subagent concerns.
 
-src/commands.ts
-  Slash command parsing and handlers.
+src/runtime/lifecycle.ts
+  Pi lifecycle hooks: session_start, before_agent_start, turn_start.
 
-src/hooks.ts
-  Pi event hooks: before_agent_start, tool_call, tool_result, turn_start.
+src/runtime/tool-hooks.ts
+  Pi tool hooks: tool_call, tool_result.
 
 src/index.ts
   Extension composition only: register hooks and commands.
@@ -76,16 +90,15 @@ Move pure functions without behavior change:
 - URL cache → `cache.ts`
 - `buildBundle`, `renderBundle`, `formatExplain` → `bundle.ts`
 
-Keep compatibility exports from `context-tree.ts` during transition.
+Keep `context-tree.ts` as a curated compatibility facade over `public-api.ts` during transition.
 
 ### Phase 2 — Pi integration split
 
 Move side-effectful code:
 
 - TUI state/rendering → `tui.ts`
-- command handlers → `commands.ts`
-- hook handlers → `hooks.ts`
-- session creation → `sessions.ts`
+- command handlers → grouped `commands/*-commands.ts` modules
+- hook handlers → `runtime/lifecycle.ts` and `runtime/tool-hooks.ts`
 
 `index.ts` should become short.
 
@@ -147,13 +160,14 @@ Implemented:
 - bundle hash/render;
 - read injection;
 - edit/write preflight;
-- scoped session creation;
+- user-global config loading via `~/.pi/CONTEXT.json` / `PI_CONTEXT_TREE_GLOBAL`;
 - basic scope guard fallback;
 - structured compact TUI with on-demand details;
 - tests for core behavior.
 
 Partial or planned:
 
+- `session:spawn` remains a schema hook for future config-driven session workflows; the old `/ct-new` command has been removed;
 - defaults cascade is currently basic, not deeply modeled/tested across all fields;
 - token budget is represented but not fully enforced;
 - `context` hook is not used yet;
@@ -165,9 +179,8 @@ Partial or planned:
 
 ## Release guidance
 
-For a first public release, prefer transparency:
+For public releases, prefer transparency:
 
-- call the release `0.1.0`;
-- describe current MVP clearly;
+- describe current runtime and command surface exactly;
 - mark subagents/guardrails/config-maintenance as planned;
 - keep architecture-review doc visible to contributors.

docs/implementation.md

@@ -252,8 +252,10 @@ Context Tree commands use `/ct-*` for discoverability:
 /ct-fetch <path>           compile bundle and fetch/cache inline URLs
 /ct-cache-list             show URL cache directory
 /ct-cache-refresh <path>   refresh cached URL sources for target
+/ct-toggle on|off          toggle entire Context Tree extension runtime
 /ct-tui on|off             toggle Context Tree widget
-/ct-new <path> [prompt]    create new Pi session seeded with session:spawn bundle
+/ct-init [--resume]        initialize editable Context Tree config
+/ct-init-review <proposal> review agent proposal inside current init flow
 /ct-subagent <path> <task> planned subagent handoff via subagent:spawn
 ```
 
@@ -262,6 +264,7 @@ Context Tree commands use `/ct-*` for discoverability:
 - Prefer `mode: { "type": "ref" }` for broad docs.
 - Use `inline`, `sections`, `markers`, `lines`, or `segments` for invariants needed before edit/write.
 - Keep `session:start` deliberate: inline core startup docs only when always useful.
+- Keep user-global `~/.pi/CONTEXT.json` config small, reference-first, and portable across repositories.
 - Put domain rules near domain scope.
 - Use exclusions for tests/generated files.
 - Do not inject `AGENTS.md`; Pi already loads it.

docs/schema.md

@@ -45,6 +45,14 @@ hook + optional target path
 
 Scope is implicit: `dirname(CONTEXT.json)`.
 
+A user-global config can also be placed at:
+
+```text
+~/.pi/CONTEXT.json
+```
+
+It is loaded before project scopes for every repository. Its file sources resolve relative to that global config directory. Path-aware `match[]` patterns are evaluated against the target path relative to the current repository root. Set `PI_CONTEXT_TREE_GLOBAL=/path/to/CONTEXT.json` to override the default location, including in tests.
+
 ## stability
 
 `stability` is a top-level scope signal for AI-assisted editing. It tells agents whether code under this scope is trusted reference, stable working code, active work, prototype, deprecated, or generated. It is not an edit policy engine; detailed rules still belong in hook-injected `.md` files.

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-context-tree",
-	"version": "0.2.1",
+	"version": "0.2.2",
 	"description": "Pi extension for deterministic path-scoped contextualization via CONTEXT.json files.",
 	"repository": {
 		"type": "git",

schemas/context.schema.json

@@ -835,7 +835,13 @@
       ],
       "additionalProperties": false
     },
-    "permissions": {},
+    "permissions": {
+      "type": "object",
+      "properties": {
+        "scopeGuard": {}
+      },
+      "additionalProperties": {}
+    },
     "subagents": {}
   },
   "required": [