gewenyu99 · Sep 23, 2026 · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026
@@ -25,7 +25,7 @@ example under [src/frameworks](../../../src/frameworks/). Framework-specific
 detection, context, environment conventions, and UI metadata belong here.
 Integration instructions and examples belong in context-mill.
 
-1. Add the integration to [Integration](../../../src/lib/constants.ts). Its
+1. Add the integration to [Integration](../../../src/shared/constants.ts). Its
    order controls first-match detection and the framework picker. Keep specific
    frameworks before language fallbacks and generic Node last; preserve the
    overlap rules in the
@@ -59,7 +59,7 @@ itself.
 | [Laravel](../../../src/frameworks/laravel/) | Composer and framework-specific filesystem signals                                                                          |
 | [Rails](../../../src/frameworks/rails/)     | Gemfile detection and Ruby conventions                                                                                      |
 
-Use [bounded filesystem helpers](../../../src/utils/bounded-fs.ts) for project
+Use [bounded filesystem helpers](../../../src/shared/utils/bounded-fs.ts) for project
 scans and reads. They bound traversal and skip dependency/build directories; add
 framework-specific exclusions with `extraIgnore`. Keep complex parsers and
 detectors beside the config so they can be checked independently.
@@ -71,7 +71,7 @@ matching integration reference and task-skill variants for the framework. A
 registry entry alone does not provide integration knowledge. The orchestrator
 resolves framework variants from the skill menu and rejects missing task
 variants; see the
-[orchestrator runner](../../../src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts).
+[orchestrator runner](../../../src/agent/runner/sequence/orchestrator/orchestrator-runner.ts).
 
 Keep project-specific facts in configuration and reusable integration guidance
 in that content. Model IDs, reasoning efforts, and gateway-required system

@@ -21,7 +21,7 @@ guide owns the fallback criteria and gateway model/effort/system-prompt
 contract.
 
 These are contribution defaults. Current runtime
-[bindings](../../../src/lib/agent/runner/switchboard/index.ts) still default
+[bindings](../../../src/agent/runner/switchboard/index.ts) still default
 many programs to Anthropic plus linear; documentation changes do not migrate
 them.
 
@@ -56,14 +56,14 @@ changing execution behavior.
    agent work.
 2. Supply the flow's seed and task prompts in context-mill, including the task
    dependencies and applicable skill variants. The
-   [orchestrator](../../../src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts)
+   [orchestrator](../../../src/agent/runner/sequence/orchestrator/orchestrator-runner.ts)
    loads `agentFlow ?? id`, requires a seed prompt, and checks task-skill
    variants before running. `run.skillId` alone does not define this flow.
 3. Register the config in
    [PROGRAM_REGISTRY](../../../src/lib/programs/program-registry.ts) and add its
    Pi/orchestrator entry to
-   [PROGRAM_BINDINGS](../../../src/lib/agent/runner/switchboard/index.ts).
-   [Existing binding checks](../../../src/lib/agent/runner/__tests__/switchboard.test.ts)
+   [PROGRAM_BINDINGS](../../../src/agent/runner/switchboard/index.ts).
+   [Existing binding checks](../../../src/agent/runner/__tests__/switchboard.test.ts)
    enforce coverage; `ProgramId` currently widens to `string`.
 4. For a standalone native command, create a command module with
    [nativeCommandFactory](../../../src/commands/factories/native-command-factory.ts)
@@ -93,7 +93,7 @@ config directly and adds prerequisite detection.
 
 `ProgramRun.customPrompt`, `abortCases`, `postRun`, and `buildOutroData` are
 consumed by the
-[linear sequence](../../../src/lib/agent/runner/sequence/linear.ts). `postRun`
+[linear sequence](../../../src/agent/runner/sequence/linear.ts). `postRun`
 runs after success; `buildOutroData` receives session and credentials, with host
 information inside credentials. The orchestrator currently uses its own task
 prompts, failure handling, and outro, and does not invoke those hooks. Check

@@ -114,7 +114,7 @@ MCP snapshots are plain `.txt`; the CI snapshot route writes colored `.ans`
 frames. Keep the screen path and failure evidence with the snapshots. Do not
 stop a progressing run at an invented turn count: the MCP exposes no turn limit;
 Pi's continuation and tool-call guards are described in its
-[harness README](../../../src/lib/agent/runner/harness/pi/README.md).
+[harness README](../../../src/agent/runner/harness/pi/README.md).
 
 ## Sweep the workbench
 

@@ -48,6 +48,6 @@ layout must update on terminal resize; reading `useStdout` alone does not
 subscribe. Account for the shell's title, hints, tabs, status expansion, and
 optional HUD rather than allocating the full terminal height to screen content.
 
-Write diagnostics through [logToFile](../../../../src/utils/debug.ts), which
+Write diagnostics through [logToFile](../../../../src/shared/utils/debug.ts), which
 uses the configured wizard log destination. Avoid introducing a separate
 hardcoded temporary log or writing debug lines into the live TUI.
@@ -38,7 +38,7 @@ Mode selection belongs to command/runner entry points. The
 [default integration command](../../../../src/commands/basic-integration/index.ts)
 routes explicit CI/headless requests separately and rejects a detected
 noninteractive environment for the ordinary interactive path.
-[Environment detection](../../../../src/utils/environment.ts) checks
+[Environment detection](../../../../src/shared/utils/environment.ts) checks
 stdout/stderr TTY state outside development mode; checking stdin alone does not
 describe this command's behavior.
 

@@ -22,8 +22,8 @@ infrastructure should consume those boundaries.
 | Framework detection, context, env conventions         | [FrameworkConfig](../../../src/lib/framework-config.ts) and [framework configs](../../../src/frameworks/)                                                                       |
 | Integration instructions and orchestrator flows/tasks | [context-mill](https://github.com/PostHog/context-mill)                                                                                                                         |
 | Programs, steps, prerequisites and outcomes           | [programs](../../../src/lib/programs/)                                                                                                                                          |
-| Sequence, harness, model and effort selection         | [switchboard](../../../src/lib/agent/runner/switchboard/)                                                                                                                       |
-| Local tool permissions and scanner adapters           | [agent-interface](../../../src/lib/agent/agent-interface.ts), [YARA hooks](../../../src/lib/yara-hooks.ts), [Pi security](../../../src/lib/agent/runner/harness/pi/security.ts) |
+| Sequence, harness, model and effort selection         | [switchboard](../../../src/agent/runner/switchboard/)                                                                                                                       |
+| Local tool permissions and scanner adapters           | [agent-interface](../../../src/agent/agent-interface.ts), [YARA hooks](../../../src/agent/yara-hooks.ts), [Pi security](../../../src/agent/runner/harness/pi/security.ts) |
 | Scanner rules                                         | [warlock](https://github.com/PostHog/warlock)                                                                                                                                   |
 | Token admission and budgets                           | [PostHog mint endpoint](https://github.com/PostHog/posthog/blob/master/posthog/llm/wizard_gateway_token.py) and [ai-gateway](https://github.com/PostHog/ai-gateway)             |
 | Screen resolution and rendering                       | [TUI](../../../src/ui/tui/) through [WizardUI](../../../src/ui/wizard-ui.ts)                                                                                                    |
@@ -43,7 +43,7 @@ infrastructure should consume those boundaries.
   new Anthropic models.
 
 Existing routing has not all migrated:
-[DEFAULT_BINDING](../../../src/lib/agent/runner/switchboard/index.ts) still
+[DEFAULT_BINDING](../../../src/agent/runner/switchboard/index.ts) still
 selects Anthropic + linear, with per-program and flag overrides. Set new
 bindings explicitly. Migrating an existing program requires checking its flow,
 tasks, and lifecycle hooks; changing the default constant alone is insufficient.
@@ -52,8 +52,8 @@ Both harnesses implement `run` and `runTask`.
 Adding a model or effort is a cross-repository change:
 
 1. Define the Wizard model ID and capabilities in
-   [constants](../../../src/lib/constants.ts) and
-   [models](../../../src/lib/agent/runner/switchboard/models.ts); select it
+   [constants](../../../src/shared/constants.ts) and
+   [models](../../../src/agent/runner/switchboard/models.ts); select it
    through the switchboard or supported context-mill stage metadata.
 2. Check the PostHog mint's `WIZARD_MODEL_ALLOWLIST` and allowed efforts. The
    token's policy is enforced by the gateway; a local constant or CLI override
@@ -65,7 +65,7 @@ Adding a model or effort is a cross-repository change:
 4. Verify the chosen harness transport and effective effort with the same
    admission policy used by the target environment.
 
-Local [commandments](../../../src/lib/agent/runner/switchboard/commandments.ts)
+Local [commandments](../../../src/agent/runner/switchboard/commandments.ts)
 provide runtime and tool guidance. They do not replace the gateway's required
 safety prompt. Keep gateway policy owned there rather than copying it into
 skills. Do not infer per-model effort authorization merely from the local
@@ -94,7 +94,7 @@ only when it gives a real owner a smaller, reusable boundary.
 
 ## Lifecycle and security
 
-[runner/index.ts](../../../src/lib/agent/runner/index.ts) bootstraps, resolves a
+[runner/index.ts](../../../src/agent/runner/index.ts) bootstraps, resolves a
 binding, and dispatches to a sequence. `agent-runner.ts` is a compatibility
 re-export, not the implementation. Sequences own their lifecycle; harnesses own
 SDK calls. `ProgramRun.postRun`, `buildOutroData`, `customPrompt`, and
@@ -109,10 +109,10 @@ than assuming every rejection terminates the run. New scanner rules belong in
 warlock; changes to how a match is handled belong in Wizard.
 
 User-provided secrets should travel through
-[secret-vault](../../../src/lib/secret-vault.ts) references. Tool
+[secret-vault](../../../src/shared/secret-vault.ts) references. Tool
 implementations resolve values host-side where they are used; they must not
 return the raw value to the model. Inspect the
-[wizard-tools](../../../src/lib/wizard-tools/) implementations and the Pi
+[wizard-tools](../../../src/agent/tools/) implementations and the Pi
 adapter when extending this shared tool surface.
 
 ## Verification and maintenance

@@ -16,19 +16,19 @@ readiness hooks, and traverse steps and gates.
 detection in `onReady`. Noninteractive execution has its own lifecycle in
 [run-non-interactive.ts](../../../../src/lib/runners/run-non-interactive.ts).
 
-[runner/index.ts](../../../../src/lib/agent/runner/index.ts) resolves a
+[runner/index.ts](../../../../src/agent/runner/index.ts) resolves a
 program's `run` definition, calls shared bootstrap, selects a binding,
 dispatches the sequence, and flushes the scanner report on cleanup. The old
-[agent-runner.ts](../../../../src/lib/agent/agent-runner.ts) is a compatibility
+[agent-runner.ts](../../../../src/agent/agent-runner.ts) is a compatibility
 export.
 
 | Layer           | Source and responsibility                                                                                                                                                      |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Bootstrap       | [shared/bootstrap.ts](../../../../src/lib/agent/runner/shared/bootstrap.ts): shared health/settings/auth/flag and MCP setup                                                    |
-| Switchboard     | [switchboard/index.ts](../../../../src/lib/agent/runner/switchboard/index.ts): resolve sequence, harness, model and effort override                                            |
-| Linear sequence | [sequence/linear.ts](../../../../src/lib/agent/runner/sequence/linear.ts): one conversation, skill/prompt assembly, post-run hooks and outro                                   |
-| Orchestrator    | [orchestrator-runner.ts](../../../../src/lib/agent/runner/sequence/orchestrator/orchestrator-runner.ts): seed plan, task queue, focused conversations, handoffs and completion |
-| Harness         | [harness/types.ts](../../../../src/lib/agent/runner/harness/types.ts): SDK boundary, implemented by Pi and Anthropic                                                           |
+| Bootstrap       | [shared/bootstrap.ts](../../../../src/agent/runner/shared/bootstrap.ts): shared health/settings/auth/flag and MCP setup                                                    |
+| Switchboard     | [switchboard/index.ts](../../../../src/agent/runner/switchboard/index.ts): resolve sequence, harness, model and effort override                                            |
+| Linear sequence | [sequence/linear.ts](../../../../src/agent/runner/sequence/linear.ts): one conversation, skill/prompt assembly, post-run hooks and outro                                   |
+| Orchestrator    | [orchestrator-runner.ts](../../../../src/agent/runner/sequence/orchestrator/orchestrator-runner.ts): seed plan, task queue, focused conversations, handoffs and completion |
+| Harness         | [harness/types.ts](../../../../src/agent/runner/harness/types.ts): SDK boundary, implemented by Pi and Anthropic                                                           |
 
 The contribution policy is
 [Pi by default, orchestration preferred](../SKILL.md#execution-policy-and-model-admission).
@@ -40,7 +40,7 @@ route.
 
 ### Configuration hooks
 
-Read [ProgramRun](../../../../src/lib/agent/runner/shared/types.ts) for exact
+Read [ProgramRun](../../../../src/agent/runner/shared/types.ts) for exact
 signatures.
 
 | Surface                                | Current consumer                                               |
@@ -70,25 +70,25 @@ binding and stamping a trace of the selected precedence rungs.
 - Sequence: composed linear clamp, development CLI override, `runTask`
   capability clamp, program flag route, sequence experiment, binding/default.
 
-[Harness](../../../../src/lib/agent/runner/switchboard/harness.ts) and
-[sequence](../../../../src/lib/agent/runner/switchboard/sequence.ts) contain the
+[Harness](../../../../src/agent/runner/switchboard/harness.ts) and
+[sequence](../../../../src/agent/runner/switchboard/sequence.ts) contain the
 exact chains. Published builds omit CLI overrides. `RUN_SURFACE` can disable
 harness experiments; static bindings and harness capabilities also affect
 resolution. Composed sub-runs remain linear even when a CLI override requests
 orchestration.
 
 Effort resolves in two stages: the binding supplies an override, then
-[modelCapabilities](../../../../src/lib/agent/runner/switchboard/models.ts)
+[modelCapabilities](../../../../src/agent/runner/switchboard/models.ts)
 applies capabilities and defaults. All selected models and efforts must also be
 admitted by the minted token and gateway. Local routing cannot bypass that
 external policy; see the
 [model admission checklist](../SKILL.md#execution-policy-and-model-admission).
 
 Flags belong in
-[switchboard/flags](../../../../src/lib/agent/runner/switchboard/flags/).
+[switchboard/flags](../../../../src/agent/runner/switchboard/flags/).
 Experiments declare their program scope; malformed payloads yield no experiment
 route. Reuse the
-[switchboard tests](../../../../src/lib/agent/runner/__tests__/switchboard.test.ts)
+[switchboard tests](../../../../src/agent/runner/__tests__/switchboard.test.ts)
 and experiment tests to check full bindings and isolation of unrelated programs.
 Do not add a second flag-reading path inside a harness or sequence.
 
@@ -99,17 +99,17 @@ Wizard's local tool boundary separately restricts operations on the user's
 project. Local commandments provide model guidance; they are not an enforcement
 mechanism.
 
-- [agent-interface.ts](../../../../src/lib/agent/agent-interface.ts) configures
+- [agent-interface.ts](../../../../src/agent/agent-interface.ts) configures
   the Anthropic SDK's tool permissions, sandbox, and gateway transport.
-- [yara-hooks.ts](../../../../src/lib/yara-hooks.ts) adapts warlock scans to SDK
+- [yara-hooks.ts](../../../../src/agent/yara-hooks.ts) adapts warlock scans to SDK
   tool hooks.
-- [Pi security](../../../../src/lib/agent/runner/harness/pi/security.ts) adapts
+- [Pi security](../../../../src/agent/runner/harness/pi/security.ts) adapts
   shared permissions and scanning to Pi tool-call/result events, including
   blocking, violation latching, and tool-call limits.
-- [Pi harness](../../../../src/lib/agent/runner/harness/pi/) explicitly supplies
+- [Pi harness](../../../../src/agent/runner/harness/pi/) explicitly supplies
   tools, scrubs shell environments, and disables project-controlled
   extensions/context loading.
-- [triage-provider.ts](../../../../src/lib/agent/triage-provider.ts) supplies
+- [triage-provider.ts](../../../../src/agent/triage-provider.ts) supplies
   gateway-backed classification for scanner findings.
 
 Scanner rules live in [warlock](https://github.com/PostHog/warlock); Wizard owns
@@ -119,16 +119,16 @@ terminates the run. Check each adapter's state machine when changing rejection
 handling. Preserve useful rejection diagnostics without logging secret content.
 
 Both SDK paths use a scoped gateway token minted through
-[gateway-session.ts](../../../../src/lib/gateway-session.ts), not the user's raw
+[gateway-session.ts](../../../../src/agent/gateway-session.ts), not the user's raw
 OAuth credential as a model API key. Rejection and refresh behavior belong at
 that seam; do not restore a legacy-gateway fallback to bypass admission.
 
 ### Secret vault: keeping values out of the model
 
-[secret-vault.ts](../../../../src/lib/secret-vault.ts) stores user-provided
+[secret-vault.ts](../../../../src/shared/secret-vault.ts) stores user-provided
 values in memory and returns opaque references. Sensitive `wizard_ask` answers
 become `secret:<uuid>` refs; `set_env_values` resolves the ref host-side when
-writing. Follow [wizard-tools](../../../../src/lib/wizard-tools/) and the Pi
+writing. Follow [wizard-tools](../../../../src/agent/tools/) and the Pi
 adapters when adding a secret-consuming tool. Return references and metadata to
 the agent, never the raw value. References are session-scoped, not durable
 credentials.
@@ -145,7 +145,7 @@ business logic.
 
 Harness adapters translate SDK messages, status markers, task updates and tool
 activity into WizardUI calls. Anthropic message processing lives in
-[agent-interface.ts](../../../../src/lib/agent/agent-interface.ts); Pi uses its
+[agent-interface.ts](../../../../src/agent/agent-interface.ts); Pi uses its
 own session event handlers. Orchestrated tasks also have queue and handoff
 state. Do not assume all harness output passes through `handleSDKMessage`.
 
@@ -165,7 +165,7 @@ separate surfaces. The Anthropic SDK's MCP integration and Pi's adapter expose
 them differently; inspect the selected harness rather than assuming identical
 tool names or discovery. Context-mill supplies skills and flow/task prompts.
 
-[Middleware](../../../../src/lib/middleware/) provides opt-in message/phase
+[Middleware](../../../../src/agent/middleware/) provides opt-in message/phase
 instrumentation. The linear sequence creates the benchmark pipeline; there is no
 pipeline construction in the compatibility `agent-runner.ts`. Inspect the actual
 consumer before extending instrumentation to another sequence or harness.