PostHog · gewenyu99 · Sep 25, 2026 · Sep 21, 2026 · Sep 21, 2026 · Sep 21, 2026
@@ -20,44 +20,44 @@ creating its own runner or changing existing routing defaults.
 
 ## Extend the framework configuration
 
-Start with [FrameworkConfig](../../../src/lib/framework-config.ts) and a nearby
-example under [src/frameworks](../../../src/frameworks/). Framework-specific
+Start with [FrameworkConfig](../../../src/programs/framework-config.ts) and a nearby
+example under [src/programs/frameworks](../../../src/programs/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/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
-   [detection checks](../../../src/lib/detection/__tests__/framework.test.ts).
-2. Add the config under `src/frameworks/<name>/<name>-wizard-agent.ts`. Use a
+   [detection checks](../../../src/programs/detection/__tests__/framework.test.ts).
+2. Add the config under `src/programs/frameworks/<name>/<name>-wizard-agent.ts`. Use a
    `type` for framework context so it satisfies `Record<string, unknown>`.
    Export the config; the integration program already supplies execution.
-3. Import the config into [FRAMEWORK_REGISTRY](../../../src/lib/registry.ts).
+3. Import the config into [FRAMEWORK_REGISTRY](../../../src/programs/frameworks/registry.ts).
    The display label comes from `metadata.name`.
 
 Read the current interface for the complete required fields. In particular,
 `detection.detectPackageManager` is required: reuse an adapter from
-[package-manager detection](../../../src/lib/detection/package-manager.ts). Use
+[package-manager detection](../../../src/programs/detection/package-manager.ts). Use
 `metadata.setup.questions` for unresolved project variants; `gatherContext`
 collects framework context. Optional notices and extra MCP servers also belong
 in metadata.
 
 Use `usesPackageJson: false` for frameworks without a package.json dependency.
 Their required `getVersion` callback can return `undefined`. Minimum-version
 checking requires both `minimumVersion` and `getInstalledVersion`; unknown
-versions pass. [Context detection](../../../src/lib/detection/context.ts)
+versions pass. [Context detection](../../../src/programs/detection/context.ts)
 returns unsupported-version data for the integration UI rather than aborting
 itself.
 
 ## Detection and examples
 
 | Starting point                              | Pattern to reuse                                                                                                            |
 | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| [Next.js](../../../src/frameworks/nextjs/)  | `hasDeclaredDependency` from `utils/package-json`, `tryGetPackageJson` from `utils/setup-utils`, and router setup questions |
-| [Django](../../../src/frameworks/django/)   | Python project files, context gathering, and Python package-manager detection                                               |
-| [Laravel](../../../src/frameworks/laravel/) | Composer and framework-specific filesystem signals                                                                          |
-| [Rails](../../../src/frameworks/rails/)     | Gemfile detection and Ruby conventions                                                                                      |
+| [Next.js](../../../src/programs/frameworks/nextjs/)  | `hasDeclaredDependency` from `utils/package-json`, `tryGetPackageJson` from `utils/setup-utils`, and router setup questions |
+| [Django](../../../src/programs/frameworks/django/)   | Python project files, context gathering, and Python package-manager detection                                               |
+| [Laravel](../../../src/programs/frameworks/laravel/) | Composer and framework-specific filesystem signals                                                                          |
+| [Rails](../../../src/programs/frameworks/rails/)     | Gemfile detection and Ruby conventions                                                                                      |
 
 Use [bounded filesystem helpers](../../../src/shared/utils/bounded-fs.ts) for project
 scans and reads. They bound traversal and skip dependency/build directories; add
@@ -88,7 +88,7 @@ content-mill variants. For an end-to-end run, use a disposable test app and the
 [exploration guide](../exploring-the-wizard/SKILL.md).
 
 For prompt, environment-upload, or outro changes, inspect the current
-[integration program](../../../src/lib/programs/posthog-integration/) and the
+[integration program](../../../src/programs/posthog-integration/) and the
 selected sequence. Some fields remain in the interface without a current
 consumer: `getOutroNextSteps` is not used by the integration outro. Linear
 post-run/outro hooks are not shared by the orchestrator; see the

@@ -32,10 +32,10 @@ them.
   [Context-mill](https://github.com/PostHog/context-mill) owns skill content and
   `cliEntries`. A new skill-backed child of an existing family ships through
   context-mill; inspect
-  [family dispatch](../../../src/lib/programs/dispatch-family.ts). Unpromoted
+  [family dispatch](../../../src/programs/dispatch-family.ts). Unpromoted
   skills run through [the skill command](../../../src/commands/skill.ts).
 - **Native program:** use a
-  [ProgramConfig](../../../src/lib/programs/program-step.ts) when the wizard
+  [ProgramConfig](../../../src/programs/program-step.ts) when the wizard
   needs its own flow, screens, detection, composition, or other native behavior.
   Keep product instructions in context-mill.
 
@@ -45,12 +45,12 @@ is `id`, not the retired `flowKey`.
 
 ## Build a native orchestrator program
 
-Use [metrics](../../../src/lib/programs/metrics/) as the current Pi/orchestrator
+Use [metrics](../../../src/programs/metrics/) as the current Pi/orchestrator
 example and read the
 [runner architecture](../wizard-development/references/ARCHITECTURE.md) when
 changing execution behavior.
 
-1. Add the program config under `src/lib/programs/<name>/`. Set `agentFlow` when
+1. Add the program config under `src/programs/<name>/`. Set `agentFlow` when
    its content-mill flow differs from `id`; setting it explicitly also documents
    the content dependency. Keep a `run` definition so the outer runner executes
    agent work.
@@ -60,7 +60,7 @@ changing execution behavior.
    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
+   [PROGRAM_REGISTRY](../../../src/programs/program-registry.ts) and add its
    Pi/orchestrator entry to
    [PROGRAM_BINDINGS](../../../src/agent/runner/switchboard/index.ts).
    [Existing binding checks](../../../src/agent/runner/__tests__/switchboard.test.ts)
@@ -70,7 +70,7 @@ changing execution behavior.
    and register it in [bin.ts](../../../bin.ts). A native family child uses the
    handlers in family dispatch. Program registration derives screen sequences
    and store lookup, not the top-level CLI `.use()` chain.
-5. Check [program OAuth scopes](../../../src/lib/oauth/program-scopes.ts)
+5. Check [program OAuth scopes](../../../src/programs/oauth/program-scopes.ts)
    against the tools the program needs; add scopes only when the base set is
    insufficient.
 
@@ -82,13 +82,13 @@ or changing gateway-required prompt material.
 ## Simple linear programs and existing flows
 
 For a very simple linear flow, use
-[createSkillProgram](../../../src/lib/programs/agent-skill/index.ts) to
+[createSkillProgram](../../../src/programs/agent-skill/index.ts) to
 configure installation of one skill. Register the native program as above with
 an explicit Pi/linear binding; the factory does not select a sequence. Read
 `SkillProgramOptions` for required fields;
-[audit](../../../src/lib/programs/audit/) demonstrates factory customization and
+[audit](../../../src/programs/audit/) demonstrates factory customization and
 a dynamic `run(session)` that seeds a ledger.
-[Revenue analytics](../../../src/lib/programs/revenue-analytics/) builds its
+[Revenue analytics](../../../src/programs/revenue-analytics/) builds its
 config directly and adds prerequisite detection.
 
 `ProgramRun.customPrompt`, `abortCases`, `postRun`, and `buildOutroData` are
@@ -102,9 +102,9 @@ does not preserve these behaviors automatically.
 
 ## Screens, prerequisites, and composition
 
-Reuse [AGENT_SKILL_STEPS](../../../src/lib/programs/agent-skill/steps.ts):
+Reuse [AGENT_SKILL_STEPS](../../../src/programs/agent-skill/steps.ts):
 intro, health check, auth, run, outro, and keep-skills. Auth also applies the
-shared [AI opt-in gate](../../../src/lib/programs/ai-opt-in-gate.ts) for agent
+shared [AI opt-in gate](../../../src/programs/ai-opt-in-gate.ts) for agent
 programs. Override `screenId`, not `screen`, when adapting a step. New screens
 need an entry in [ScreenId](../../../src/ui/tui/screen-sequences.ts), a
 component, and registration in
@@ -123,12 +123,12 @@ prerequisite strategy.
 `requires` currently records metadata; it does not execute or enforce prior
 programs. Compose real work through `ProgramStep.run`, with `onRunPrep` and
 `targetDir` when needed. The
-[integration run step](../../../src/lib/programs/posthog-integration/index.ts)
-and [self-driving](../../../src/lib/programs/self-driving/) demonstrate this.
+[integration run step](../../../src/programs/posthog-integration/index.ts)
+and [self-driving](../../../src/programs/self-driving/) demonstrate this.
 Composed sub-runs are structurally linear; orchestrators cannot nest. A host run
 step without `run` can also set `targetDir` and `onRunPrep` to scope the
 program's own agent to a picked project and keep its sequence, as
-[error-tracking](../../../src/lib/programs/error-tracking/) does.
+[error-tracking](../../../src/programs/error-tracking/) does.
 
 ## Validate the affected path
 

@@ -129,5 +129,5 @@ The shared log is `/tmp/posthog-wizard.log`. Record its byte count before a run
 and read from that count plus one afterward. Run sweeps serially so their logs
 remain attributable. `read_state` omits `frameworkContext`; an empty
 `setupQuestions` list alone does not prove a router mode. When necessary,
-inspect the detector under [`src/frameworks/`](../../../src/frameworks/) against
+inspect the detector under [`src/programs/frameworks/`](../../../src/programs/frameworks/) against
 the same fixture.
@@ -40,7 +40,7 @@ conventions rather than copying upstream component manuals.
 3. Register the component in
    [screen-registry.tsx](../../../src/ui/tui/screen-registry.tsx).
 4. Reference it through `screenId` in the owning
-   [program's steps](../../../src/lib/programs/), with the appropriate
+   [program's steps](../../../src/programs/), with the appropriate
    visibility, completion, and gate predicates.
 
 Screen sequences derive from program steps. Do not hand-maintain a second

@@ -5,7 +5,7 @@
 | Surface                                                           | Owns                                                                          |
 | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- |
 | [WizardSession](../../../../src/lib/wizard-session.ts)            | Run configuration, decisions, credentials, and lifecycle state                |
-| [ProgramStep](../../../../src/lib/programs/program-step.ts)       | Screens, visibility/completion predicates, gates, and initialization hooks    |
+| [ProgramStep](../../../../src/programs/program-step.ts)       | Screens, visibility/completion predicates, gates, and initialization hooks    |
 | [screen-sequences.ts](../../../../src/ui/tui/screen-sequences.ts) | `ScreenId`, `Screen`, `Sequence`, and the derived `PROGRAM_SEQUENCES`         |
 | [WizardRouter](../../../../src/ui/tui/router.ts)                  | Resolution and the `Overlay` stack                                            |
 | [WizardStore](../../../../src/ui/tui/store.ts)                    | Reactive state, gate promises, display observations, and pending interactions |
@@ -17,7 +17,7 @@
 entries: `id`, `show`, and `isComplete`. Completion defaults to the step's
 `gate` when no separate `isComplete` is provided. Steps without a screen are
 omitted, and the exit screen is appended. The projection applies
-[withAiOptInGate](../../../../src/lib/programs/ai-opt-in-gate.ts) consistently
+[withAiOptInGate](../../../../src/programs/ai-opt-in-gate.ts) consistently
 with store gate creation.
 
 `WizardRouter.resolve(session)` first checks the overlay stack, then returns the

@@ -19,9 +19,9 @@ infrastructure should consume those boundaries.
 
 | Concern                                               | Owner                                                                                                                                                                           |
 | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Framework detection, context, env conventions         | [FrameworkConfig](../../../src/lib/framework-config.ts) and [framework configs](../../../src/frameworks/)                                                                       |
+| Framework detection, context, env conventions         | [FrameworkConfig](../../../src/programs/framework-config.ts) and [framework configs](../../../src/programs/frameworks/)                                                                       |
 | Integration instructions and orchestrator flows/tasks | [context-mill](https://github.com/PostHog/context-mill)                                                                                                                         |
-| Programs, steps, prerequisites and outcomes           | [programs](../../../src/lib/programs/)                                                                                                                                          |
+| Programs, steps, prerequisites and outcomes           | [programs](../../../src/programs/)                                                                                                                                          |
 | 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)                                                                                                                                   |
@@ -34,7 +34,7 @@ infrastructure should consume those boundaries.
   are separate: Pi supports gateway-backed Anthropic and OpenAI transports.
 - **Prefer orchestration.** A seed agent plans work, then task agents execute
   focused conversations. Start from
-  [metrics](../../../src/lib/programs/metrics/) and its context-mill flow.
+  [metrics](../../../src/programs/metrics/) and its context-mill flow.
 - **Linear is for very simple tasks and legacy support.** Composed program
   sub-runs are also structurally clamped to linear; orchestration cannot nest
   through that seam.

@@ -54,7 +54,7 @@ signatures.
 
 Do not migrate a linear program merely by changing its binding if it depends on
 these hooks. Inspect the orchestrator's flow and completion path instead.
-[Metrics](../../../../src/lib/programs/metrics/) is a current Pi/orchestrator
+[Metrics](../../../../src/programs/metrics/) is a current Pi/orchestrator
 example. Native command modules still need registration in
 [bin.ts](../../../../bin.ts); screen sequences derive from the program registry.
 

@@ -34,8 +34,8 @@ module.exports = {
       // The agent surface. It takes resolved data in, reports through
       // progress events and asks through an injected answerer, so nothing
       // here may import a UI, the session, detection, the CLI or a program.
-      // Only direct static imports are checked. Program types stay importable
-      // until B1 moves PROGRAM_BINDINGS to programs.
+      // Only direct static imports are checked. ProgramId remains a type-only
+      // exception until PROGRAM_BINDINGS moves to programs.
       files: ['src/agent/**/*.ts'],
       excludedFiles: ['**/__tests__/**'],
       rules: {
@@ -64,9 +64,7 @@ module.exports = {
                   '**/ui',
                   '**/ui/**',
                   '@lib/**',
-                  '!@lib/programs/**',
                   '**/lib/**',
-                  '!**/lib/programs/**',
                   '**/wizard-session',
                   '**/detection',
                   '**/detection/**',
@@ -77,7 +75,6 @@ module.exports = {
                   '@steps/**',
                   '**/steps',
                   '**/steps/**',
-                  '@frameworks/**',
                   '**/frameworks/**',
                   '@utils/setup-utils',
                   '@shared/utils/setup-utils',
@@ -90,10 +87,10 @@ module.exports = {
                   'The agent reports through progress events and asks through AgentInteraction; it takes everything else through RunConfig and RunInput.',
               },
               {
-                group: ['@lib/programs/**', '**/programs/**'],
+                group: ['@programs', '@programs/**', '**/programs/**'],
                 allowTypeImports: true,
                 message:
-                  'The agent takes program data through RunConfig. Types only, until B1 moves PROGRAM_BINDINGS to programs.',
+                  'The agent takes program data through RunConfig. ProgramId types remain until PROGRAM_BINDINGS moves to programs.',
               },
             ],
           },