@polderlabs/bizar-omp 0.2.0 → 0.3.0

package/skills/omp-native-development/references/execution-and-lifecycle.md

@@ -0,0 +1,74 @@
+# Task execution, isolation and truthful completion
+
+Snapshot: `dbf3afad4894bde827d90f965e77b3fe1c5a95e5`.
+
+## Contents
+1. Dynamic task contract
+2. Async execution and completion
+3. Shared policy versus public APIs
+4. Isolation and application
+5. Follow-up and recovery
+6. Bizar evidence rules
+7. Sources
+
+## 1. Dynamic task contract
+
+Read `docs/tools/task.md` and the actual target schema. The default batch form has required shared `context` and a nonempty `tasks` array. Per-item fields include `name`, `agent`, `task`, `outputSchema`, `schemaMode`, and conditionally `effort` and `isolated`. Do not use obsolete `label` or `schema` fields or add a public `model` field.
+
+`task.batch` changes the model-facing shape. Runtime compatibility may accept flat calls while batch mode is enabled, but that does not justify writing a static schema that ignores settings. `effort` is exposed only when enabled; `isolated` additionally depends on isolation being enabled and plan mode being off.
+
+Agent names must resolve, obey parent spawn constraints and depth limits, and not be disabled. Per-item output schema takes precedence over frontmatter `output`, which precedes inherited session output schema. Explicit strict validation must succeed; a schema-shaped string in prose is not equivalent to native structured output.
+
+## 2. Async execution and completion
+
+A background task response can contain a successful spawn acknowledgement, job IDs and progress without any settled worker result. Mixed batches may return completed blocking workers while other workers remain active. Some validation failures appear as normal tool text with empty results. Interpret native status and data, not just the transport's success flag.
+
+Use separate states for admission, acknowledgement, running, settled, result validation, integration and acceptance. Native jobs and Agent Hub own worker lifecycle; Bizar's workflow journal references those IDs rather than starting its own competing job manager.
+
+Native structured results include identity, exit/error/abort status, output, usage, resolved model and fallback indicators, structured-output status, and artifact metadata when applicable. A child must finish through the native yield mechanism; recovery reminders do not transform missing proof into success. Check the effective result schema and termination state before advancing a workflow.
+
+`agent_end` is a notification and may not imply final settlement. SDK events can carry `isTerminal: false` while maintenance or async work continues. The native `session_stop` boundary applies to main sessions, not task children, and defers until owned background work is idle. Advisory continuations are bounded; explicit refusals can remain blocking until allowed or interrupted. Bizar must retain its own bounded repair policy rather than use an unbounded stop-hook loop.
+
+For SDK hosts, `await session.waitForIdle()` after prompting is a settlement barrier for native internal work. Call it outside callbacks whose completion the session itself awaits, and provide an external deadline. It is not a promise to await arbitrary detached work started by subscribers.
+
+## 3. Shared policy versus public APIs
+
+Task and eval agent paths share policy resolution, but their public arguments and defaults are not interchangeable. An internal request type can expose a model or isolation control that the public helper does not expose. Trace the model-facing schema/helper through its bridge into the shared policy resolver before claiming a parameter works.
+
+Native task lifecycle bus channels exist in source, but an event's internal emission does not establish a documented extension-visible subscription. Prove observation from the actual extension or SDK context. If a required atomic admission/result seam is unavailable, isolate a source-coupled adapter or propose an upstream API, and keep the unsupported route visibly unqualified.
+
+`workpool()` has its own process-local registry and keep-alive semantics. Do not claim it has the same isolation or application controls as individual task calls. For a managed writer workflow, either establish equivalent policy coverage or keep that route outside the supported writer profile. Do not advertise universal enforcement while leaving an alternate dispatch path unchecked.
+
+## 4. Isolation and application
+
+OMP owns creation and cleanup of its native isolation workspaces. Bizar can require captured artifacts and control whether they are eligible for integration, without constructing a second worktree runtime.
+
+The critical source-level difference: shared policy uses `task.isolation.apply` by default for task invocations, but uses `true` by default for eval invocations unless an explicit control says otherwise. Thus setting `task.isolation.apply: false` does not prove all eval-driven isolated writers will avoid applying changes. Test that route independently and require an explicit supported `apply: false` control for capture-only eval use.
+
+Read the selected backend's semantics. Copy-on-write filesystem isolation or a worktree does not necessarily isolate credentials, network, processes or arbitrary absolute paths. Backend availability and fallback also affect behavior. A security requirement needs an appropriate OS/container boundary and verified mounts, not just an `isolated` flag.
+
+Native branch application can stash the parent, cherry-pick changes and then restore the stash. A stash-pop conflict can occur after commits were already applied; the preserved stash and resulting Git state matter. Do not infer that an error means no mutation occurred. Patch artifacts and nested repository changes require similarly explicit handling.
+
+## 5. Follow-up and recovery
+
+Non-isolated agents can become idle, later parked and revivable through native messaging. Isolated workers are torn down after their workspace lifecycle and are not equivalent revivable workers. Use a new repair assignment with explicit artifact and revision references rather than directing a message at a removed isolated workspace.
+
+Children do not inherit the full parent conversation. Give each task a complete assignment, objective, relevant context, acceptance criteria, scope and output schema. Share stable references through the native `local://`, `agent://` and `history://` mechanisms where appropriate; do not assume a prompt reference makes arbitrary files accessible.
+
+On process restart, reconcile durable task/workflow evidence with native session history and actual repository state. Do not automatically re-execute a push, publish, deploy or Git integration because its completion message was lost. Such operations need an idempotency/reconciliation strategy and visible uncertain status.
+
+## 6. Bizar evidence rules
+
+The following are PROPOSED Bizar guarantees, not automatic OMP behavior: require revision-bound verification receipts; make one workflow owner authorize transitions; reject stale evidence; serialize integration; record settings and role resolution per dispatch; and cap repair iterations. Prove them in tests before advertising them.
+
+Associate evidence with candidate content/tree identity, check command and cwd, toolchain, outcome, output digests and time. After integration, run the relevant proving checks against the integrated target. A worker statement, successful spawn or passing test on a different revision must not mark the objective complete.
+
+## 7. Sources
+
+- [Native task contract](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/task.md)
+- [Shared subagent implementation](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/task/structured-subagent.ts#L268-L365)
+- [Eval tool](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/eval.md)
+- [Workpool bridge](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/eval/workpool-bridge.ts)
+- [Extension events](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/extensions.md)
+- [SDK](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/sdk.md)
+- [Retry settlement and waitForIdle](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/non-compaction-retry-policy.md)

package/skills/omp-native-development/references/extensions-and-packaging.md

@@ -0,0 +1,82 @@
+# Extensions, packages and skills
+
+Snapshot: `dbf3afad4894bde827d90f965e77b3fe1c5a95e5`.
+
+## Contents
+1. Registration and runtime boundaries
+2. Tools and interception
+3. Package discovery and installation
+4. Skills and source precedence
+5. UI and state
+6. Qualification checklist
+7. Sources
+
+## 1. Registration and runtime boundaries
+
+A native extension exports a default factory receiving `ExtensionAPI` from `@oh-my-pi/pi-coding-agent`. Register event handlers, tools, commands, shortcuts and renderers during factory initialization. Runtime actions such as sending a message require the initialized session. Plugin installation can import and initialize the factory against a throwaway surface, so network calls, database migrations, worktree creation or model requests on import are unacceptable.
+
+Use the injected schema builders such as `pi.zod` or the documented omptype APIs. The compatibility facade is not a promise of every upstream Zod/TypeBox feature. Verify the target schema API and emitted JSON schema instead of using an unrelated Zod version's behavior by analogy.
+
+Keep session-scoped resources in session bindings. On reload, switch, branch and shutdown, detach owned listeners and release resources. OMP extensions run in-process, not in an isolation boundary. Use managed context timers when deferring work; unhandled detached errors can affect the host. Do not start unowned background loops.
+
+`before_agent_start` policy preparation may be re-entered when the base prompt changes. Do not perform irreversible side effects merely because this handler ran once. Preserve attribution when injecting agent-generated text: do not mislabel generated instructions as a new human request.
+
+## 2. Tools and interception
+
+`pi.registerTool` defines native LLM-callable functionality. The current execute contract receives `toolCallId`, params, signal, update callback and context. Preserve cancellation and structured `details`; content is for display/model context, not a substitute for machine-readable status.
+
+`tool_call` can block execution or revise input. Native input revisions are revalidated and, for model-issued calls, incorporated into scheduling, events, persisted messages and approval. `tool_result` can transform results and chains through registered handlers. Observability events are not authorization gates.
+
+`ctx.invokeTool` only delegates to the native built-in with the same name as the extension tool shadowing it. A new `bizar_workflow` tool cannot use it as a general task-spawning method. Do not invent `pi.invokeTool(name, params)` or `pi.spawnAgent` without verifying an actual exported contract.
+
+`resources_discover` is present in the inspected types/runner but documented as having no AgentSession callsites. An interface definition alone does not establish a usable lifecycle event. Check callsites for every critical hook.
+
+File-write/delete fallback callbacks cover defined native primitives and permission-error paths. They do not intercept all writes through shell, eval, LSP, archives, database writes or remote interfaces. A fallback writer is privileged functionality: do not implement it as a general bypass around filesystem policy.
+
+## 3. Package discovery and installation
+
+The package manifest uses `omp.extensions` for entrypoints, with legacy `pi.extensions` compatibility. A minimal extension package can declare:
+
+```json
+{
+  "name": "@polderlabs/bizar",
+  "type": "module",
+  "omp": { "extensions": ["./src/index.ts"] }
+}
+```
+
+This is a manifest fragment, not a publish-ready package: add real versioning, dependencies/peers and tested file inclusion. Conventional sibling `agents/`, `skills/`, rules and prompts are discovered through their own documented capability paths. Do not invent `omp.agents` and assume it replaces the conventional directory contract.
+
+Native automatic extension scanning uses cwd `.omp/extensions` and the active agent directory's `extensions/`, and conventionally scans `.ts`/`.js`. Explicit manifest files may support more suffixes. Configured package directories and manifest resolution have different rules from native directory scanning. Keep one unambiguous entrypoint and test installed-package and local-development discovery.
+
+Native package commands include `omp plugin install <package@version>` and local linking, with `omp install` as a convenience target classifier. A plain skill directory is passive content; do not claim `omp install skill.zip` is a supported skill-install operation. The supplied skill ZIP should be unpacked into a skill root or loaded by the developing agent's own skill system.
+
+Plugin installation/configuration has its own data root and lockfiles, distinct from session transcripts and agent profile configuration. Do not construct all paths by concatenating `~/.omp/agent`. Use native discovery and avoid rewriting user plugin lockfiles by hand. Npm plugin updates occur by installing the new version; do not invent an update verb.
+
+## 4. Skills and source precedence
+
+Native skill discovery expects one directory level under `skills/`: `skills/<name>/SKILL.md`. Deeply nesting groups of skills does not automatically work. A native skill needs meaningful description frontmatter. Use `skill://<name>` and `skill://<name>/<relative-path>` for OMP's internal read surface; these are not web URLs.
+
+Skill providers, custom directories and managed/learned skills have separate precedence. In the inspected implementation, a custom-directory skill can override a same-named provider skill; authored skills outrank managed learned skills. Agent definition discovery has different rules, so do not use one precedence table for both.
+
+`autoloadSkills` references the parent's discovered skill names. Unknown names are silently ignored. Test that this skill was discovered, not filtered by source toggles or include/ignore settings, and actually injected into the child. The existence of an on-disk folder is not that test.
+
+`/skill:<name>` is available when skill commands are enabled. Native invocation injects the body and location; it does not execute every script inside the directory. User-invoked versus auto-injected content has different attribution. A passive skill cannot enforce tool permissions or guarantee compliance from a developing model.
+
+## 5. UI and state
+
+Prefer native command/tool rendering and Agent Hub over a parallel Bizar interface. At this pin, some extension UI methods exist but are no-ops in certain modes; for example footer/header methods are not a universal rendering seam. RPC widgets support a subset; ACP can expose elicitation while other UI methods remain inert. `hasUI` is not a complete capability matrix.
+
+Persist small branch-relevant state through namespaced custom entries, e.g. `com.polderlabs.bizar.state`. Reconstruct the current branch using the session manager rather than blindly replaying every historical branch into one mutable global state. Keep external workflow journals keyed by run and workspace identity and reconcile them explicitly with branch-local session references.
+
+## 6. Qualification checklist
+
+Verify no side effects at import; one effective entrypoint; installed-package files present; commands/tools registered once; skills and agents discovered with correct precedence; native override preservation; runtime event callsites; session switching and cleanup; cancellation; native UI behavior and headless fallback; and no unsupported internal imports leaking through the architecture.
+
+## 7. Sources
+
+- [Extension API and lifecycle](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/extensions.md)
+- [Extension loading](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/extension-loading.md)
+- [Plugin manager](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/plugin-manager-installer-plumbing.md)
+- [Skills](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills.md)
+- [omptype](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/omptype-guide.md)

package/skills/omp-native-development/references/native-validation-matrix.md

@@ -0,0 +1,96 @@
+# Native integration validation matrix
+
+## Contents
+1. Test levels
+2. Acceptance cases
+3. Result record
+
+## Test levels
+
+All cases below initially have status NOT RUN. The included native Bun file is a starter helper-contract suite, not implementation of every case. The offline Python suite validates this skill's utilities only. It cannot satisfy live OMP/Bizar release gates.
+
+Use source/type checks first, then native unit and fake-provider integration tests, then optional live endpoint smoke tests. Record actual version/commit, command, environment, provider fixture, result and evidence path for every executed case. Use disposable repositories and preserve operator settings.
+
+An inapplicable case must have a documented scope decision; a missing implementation is not an automatic waiver. Bizar-specific policies must be labeled as proposed product requirements, not pre-existing native guarantees.
+
+## Acceptance cases
+
+| ID | Area | Scenario | Required outcome |
+| --- | --- | --- | --- |
+| Q01 | Qualification | Fingerprint the real target | Record package/binary integrity, commit when available, Bun, OS, mode, profile and cwd; distinguish main from a same-version release. |
+| Q02 | Qualification | Clean native install and discovery | All expected extension tools, commands, agents and skills appear once from their intended sources. |
+| Q03 | Qualification | Import and reload | Factory import performs registration only; reload produces no duplicate callbacks, timers or model calls. |
+| Q04 | Qualification | Project agent shadowing | The exact-name project definition wins; diagnostics identify the effective source. |
+| Q05 | Qualification | Case-sensitive identities | Different agent names retain exact native matching; a case typo cannot silently route elsewhere. |
+| Q06 | Qualification | Skill autoload | The discovered skill is injected into a real child; missing/filtered skill is detected by Bizar qualification despite native silent-ignore behavior. |
+| R01 | Roles | Built-ins and custom roles | The target built-in list and configured custom roles are supported; no obsolete hard-coded role inventory. |
+| R02 | Roles | Alias chains | Configured custom role chains resolve through native helpers; original explicit role identity is retained. |
+| R03 | Roles | Agent override precedence | task.agentModelOverrides wins over the agent frontmatter selector in actual child execution. |
+| R04 | Roles | Agent default precedence | Without a settings override, the qualified frontmatter role resolves before the applicable parent fallback. |
+| R05 | Roles | Active main model versus custom roles | Changing only the main selection does not silently remap unrelated custom roles. |
+| R06 | Roles | Default agent inheritance | Singleton default aliases preserve the native active-session inheritance behavior. |
+| R07 | Roles | Task-role inheritance | Configured @task and unconfigured @task cases match native resolution, rather than a Bizar approximation. |
+| R08 | Roles | Legacy and default aliases | Supported pi/role and * spellings retain native semantics; new configuration prefers @role. |
+| R09 | Roles | Selector grammar | Colon-bearing IDs, effort suffixes and supported upstream routing are parsed by the native target. |
+| R10 | Roles | Role cycles | Native cycle/fallback behavior is measured; stricter Bizar lint is identified as Bizar policy. |
+| R11 | Roles | Unavailable required role | A missing/unavailable required model produces an explicit diagnosis or approved native fallback; no hidden arbitrary Bizar model. |
+| R12 | Roles | Live config reload | Role and agent changes made during a session affect the next native preflight, or trigger explicit strict-profile readmission. |
+| R13 | Roles | Config layers | Global, cwd-project, ordered overlays and runtime overrides retain native precedence; records merge and arrays replace. |
+| R14 | Roles | Role persistence destination | Native project role storage works without turning all settings writes into project writes. |
+| R15 | Roles | Profiles and relocated roots | Profile/agent-directory changes do not leak roles or credentials between runs. |
+| R16 | Roles | Role-specific retry identity | Fallback uses the original selected role; receipts also record the actual effective model. |
+| R17 | Roles | Authentication fallback | Missing primary auth and parent-auth fallback are visible; strict approved-provider/local-only policy is enforced before data leaves the boundary or declared unsupported. |
+| R18 | Roles | Keyless local models | A native keyless provider is not mistaken for broken authentication or silently routed remote. |
+| R19 | Roles | Disabled provider and scope | Native model/discovery disable rules and model scope are preserved, with the correct source/provider namespace. |
+| R20 | Roles | Optional effort schema | effort is present/absent with task.enableEffort and is not passed to a schema that does not expose it. |
+| R21 | Roles | Effort caps and model transitions | Coarse effort maps to actual supported levels and caps survive fallback; no invented universal high/max support. |
+| R22 | Roles | Per-agent service tiers | Exact-name override precedes subagent default; unsupported families, inherit, same/cross-family fallback and persisted empty maps are tested. |
+| R23 | Roles | Prewalk | Off/on/custom overrides, missing targets, exact no-op, same-model effort downgrade and actual model-change receipts are correct. |
+| R24 | Roles | Advisor | Child defaults, explicit overrides, selected role, cancellation and revival persistence follow native behavior. |
+| R25 | Roles | User-tagged models | m1-style branch-local identities remain generic tagged-model requests; no unwanted specialist substitution or cross-session persistence. |
+| R26 | Roles | Vibe parity | fast/sonic and good/task model overrides work; service-tier behavior is not falsely assumed identical to task/eval. |
+| R27 | Roles | Gateway capabilities | Real OmniRoute/provider IDs, endpoint format, context limits, image/tool support and hidden backend identity are qualified or explicitly unknown. |
+| R28 | Roles | Non-destructive initialization | Existing native and Bizar mappings, tags, cycles, provider settings and tiers survive setup unchanged unless an explicit diff is approved. |
+| E01 | Execution | Native task shape | No public per-call model field; context and per-item agent/output fields match the target flat/batch schema. |
+| E02 | Execution | Async acknowledgement | Spawn acknowledgement and empty results never mark a worker complete. |
+| E03 | Execution | Mixed batch | Blocking results and ongoing async jobs are reconciled independently; partial spawn failures are not lost. |
+| E04 | Execution | Strict outputs | Schema validation, missing yield, failed/aborted children and partial results cannot become successful evidence. |
+| E05 | Execution | Task capture-only isolation | Managed native task writers return artifacts without premature application. |
+| E06 | Execution | Eval capture-only isolation | Explicit supported eval apply:false is verified independently of task.isolation.apply; alternate paths cannot bypass advertised policy. |
+| E07 | Execution | Workpool coverage | Workpool behavior is qualified separately; unsupported managed-writer paths are visibly excluded, not silently advertised as equivalent. |
+| E08 | Execution | Cancellation and settlement | Cancel terminates owned work and bounded repair; terminal/idle checks do not deadlock inside awaited event callbacks. |
+| E09 | Execution | Revival differences | Non-isolated revival and non-revivable completed isolation have distinct correct follow-up paths. |
+| E10 | Execution | Native event visibility | Required lifecycle data is observed from the real extension/SDK context; internal-only events are not assumed public. |
+| E11 | Execution | Same-name delegation | invokeTool is used only for the supported same-name built-in delegation contract. |
+| S01 | Sessions | Concurrent main sessions | Independent AgentRegistry/session bindings prevent model, callback and state cross-talk. |
+| S02 | Sessions | Restricted tools | toolNames versus restrictToolNames and custom-tool exceptions behave as declared; no unsupported sandbox claim. |
+| S03 | Sessions | Branch and compaction state | Current-branch state reconstructs correctly; stale evidence from another branch cannot authorize completion. |
+| S04 | Sessions | Tool evidence taxonomy | toolResult roles and toolCall blocks are parsed correctly without substituting snake_case hook names. |
+| S05 | Sessions | SDK disposal and retry drain | Correct root exports, shared auth instance, waitForIdle and dispose semantics; retry events are not lost at teardown. |
+| S06 | Sessions | RPC and UI modes | Workflow correctness works without TUI widgets; RPC acknowledgements, UI subsets and disconnect behavior are tested. |
+| G01 | Integration | Serialized integration | Only one qualified integration path mutates the target; expected base and artifact hashes are checked. |
+| G02 | Integration | Dirty tree and partial failures | Stash/cherry-pick/patch conflict states are reconciled from actual Git state without deleting unrelated work. |
+| G03 | Integration | Fresh proof after merge | Verification is tied to the integrated candidate; source-branch success alone does not pass the objective. |
+| G04 | Integration | Irreversible-action recovery | Restart reconciles push/publish/deploy outcomes instead of blindly replaying mutations. |
+| P01 | Security | Secret hygiene | Config inspection, role reports, model changes, logs and evidence never expose credentials or secret command outputs. |
+| P02 | Security | Containment claims | Tools, eval, shell, LSP and native isolation boundaries are accurately described and separately tested where adversarial isolation is required. |
+| P03 | Security | Untrusted reference content | Repository text, retrieved docs and child outputs cannot grant authorization or rewrite operator policy. |
+| P04 | Security | Reversible migration | Existing legacy/current configuration and state are preserved; ownership-aware rollback refuses to overwrite later user changes. |
+
+## Result record
+
+```json
+{
+  "case": "R03",
+  "status": "NOT_RUN",
+  "targetCommit": null,
+  "packageIntegrity": null,
+  "command": null,
+  "evidencePath": null,
+  "limitations": []
+}
+```
+
+Change status to PASS or FAIL only after running the actual relevant test. SKIPPED requires a reason; UNKNOWN identifies an unresolved behavior. Never treat a configured role, test filename or source inspection as a live worker-routing result.
+
+Per-case primary source paths and machine-readable outcomes are provided in `assets/tests/acceptance-matrix.json`; immutable URLs are in the official documentation index.

package/skills/omp-native-development/references/official-docs-index.md

@@ -0,0 +1,174 @@
+# Official documentation index
+
+Snapshot: `dbf3afad4894bde827d90f965e77b3fe1c5a95e5`. Each link is immutable. The manifest also records the expected Git blob hash.
+
+## Contents
+
+1. Finding the correct contract
+2. Complete docs/ Markdown inventory
+3. Additional source-level contracts
+
+## Finding the correct contract
+
+Use the focused reference guides first, then open the exact upstream page for the affected subsystem. A file being indexed does not mean every statement in it was audited. `reviewed-ranges` means selected content was examined; all other rows are navigation coverage only. No upstream full-text corpus is included in this archive. Obtain one with `scripts/omp_docs.py sync`.
+
+| Work | Start here | Cross-check |
+| --- | --- | --- |
+| Agent/model roles | task-agent-discovery.md; models.md; settings.md | model-roles.ts; model-resolver.ts; native resolver tests |
+| Extensions and tools | extensions.md; custom-tools.md; extension-loading.md | actual exported types, wrappers and callsites |
+| Scheduling and isolation | tools/task.md; tools/eval.md; tools/hub.md | structured-subagent.ts; task/executor.ts; native tests |
+| Packaging and skills | skills.md; plugin-manager-installer-plumbing.md | discovery roots, package manifest |
+| Providers and gateways | models.md; providers.md; provider-endpoint-constraints.md | provider transport and catalog metadata |
+| Context and recovery | session.md; compaction.md; non-compaction-retry-policy.md | session events, retries, branch reconstruction |
+| Integration clients | sdk.md; rpc.md; collab.md | mode-specific capabilities and exported types |
+| Security | approval-mode.md; secrets.md; auth-broker-gateway.md | actual containment boundaries, not prompt claims |
+| Any other tool | tools/<tool>.md below | runtime tool schema and implementation |
+
+## Complete docs/ Markdown inventory
+
+| Path | Research status | Pinned source |
+| --- | --- | --- |
+| `docs/ERRATA-GPT5-HARMONY.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/ERRATA-GPT5-HARMONY.md) |
+| `docs/adding-a-provider.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/adding-a-provider.md) |
+| `docs/advisor-watchdog.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/advisor-watchdog.md) |
+| `docs/agent-hub.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/agent-hub.md) |
+| `docs/ai-schema-normalize.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/ai-schema-normalize.md) |
+| `docs/approval-mode.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/approval-mode.md) |
+| `docs/auth-broker-gateway.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/auth-broker-gateway.md) |
+| `docs/bash-tool-runtime.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/bash-tool-runtime.md) |
+| `docs/blob-artifact-architecture.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/blob-artifact-architecture.md) |
+| `docs/cli-reference.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/cli-reference.md) |
+| `docs/collab.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/collab.md) |
+| `docs/compaction.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/compaction.md) |
+| `docs/computer-use.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/computer-use.md) |
+| `docs/config-usage.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/config-usage.md) |
+| `docs/context-files.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/context-files.md) |
+| `docs/custom-tools.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/custom-tools.md) |
+| `docs/environment-variables.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/environment-variables.md) |
+| `docs/extension-loading.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/extension-loading.md) |
+| `docs/extensions.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/extensions.md) |
+| `docs/fs-scan-cache-architecture.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/fs-scan-cache-architecture.md) |
+| `docs/gemini-manifest-extensions.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/gemini-manifest-extensions.md) |
+| `docs/handoff-generation-pipeline.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/handoff-generation-pipeline.md) |
+| `docs/hooks.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/hooks.md) |
+| `docs/install-id.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/install-id.md) |
+| `docs/keybindings.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/keybindings.md) |
+| `docs/local-models.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/local-models.md) |
+| `docs/lsp-config.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/lsp-config.md) |
+| `docs/macos-signing-notarization.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/macos-signing-notarization.md) |
+| `docs/magic-keywords.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/magic-keywords.md) |
+| `docs/marketplace.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/marketplace.md) |
+| `docs/mcp-config.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/mcp-config.md) |
+| `docs/mcp-protocol-transports.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/mcp-protocol-transports.md) |
+| `docs/mcp-runtime-lifecycle.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/mcp-runtime-lifecycle.md) |
+| `docs/mcp-server-tool-authoring.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/mcp-server-tool-authoring.md) |
+| `docs/memory.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/memory.md) |
+| `docs/mnemosyne-memory-backend.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/mnemosyne-memory-backend.md) |
+| `docs/models.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/models.md) |
+| `docs/native-crates.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/native-crates.md) |
+| `docs/natives-addon-loader-runtime.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-addon-loader-runtime.md) |
+| `docs/natives-architecture.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-architecture.md) |
+| `docs/natives-binding-contract.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-binding-contract.md) |
+| `docs/natives-build-release-debugging.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-build-release-debugging.md) |
+| `docs/natives-media-system-utils.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-media-system-utils.md) |
+| `docs/natives-rust-task-cancellation.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-rust-task-cancellation.md) |
+| `docs/natives-shell-pty-process.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-shell-pty-process.md) |
+| `docs/natives-text-search-pipeline.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/natives-text-search-pipeline.md) |
+| `docs/non-compaction-retry-policy.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/non-compaction-retry-policy.md) |
+| `docs/notebook-tool-runtime.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/notebook-tool-runtime.md) |
+| `docs/omptype-guide.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/omptype-guide.md) |
+| `docs/plugin-manager-installer-plumbing.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/plugin-manager-installer-plumbing.md) |
+| `docs/porting-from-pi-mono.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/porting-from-pi-mono.md) |
+| `docs/porting-to-natives.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/porting-to-natives.md) |
+| `docs/prewalk.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/prewalk.md) |
+| `docs/provider-compat-reference.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/provider-compat-reference.md) |
+| `docs/provider-endpoint-constraints.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/provider-endpoint-constraints.md) |
+| `docs/provider-quirks.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/provider-quirks.md) |
+| `docs/provider-streaming-internals.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/provider-streaming-internals.md) |
+| `docs/providers.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/providers.md) |
+| `docs/python-repl.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/python-repl.md) |
+| `docs/resolve-tool-runtime.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/resolve-tool-runtime.md) |
+| `docs/rpc.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/rpc.md) |
+| `docs/rulebook-matching-pipeline.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/rulebook-matching-pipeline.md) |
+| `docs/sdk.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/sdk.md) |
+| `docs/secrets.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/secrets.md) |
+| `docs/session-operations-export-share-fork-resume.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/session-operations-export-share-fork-resume.md) |
+| `docs/session-switching-and-recent-listing.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/session-switching-and-recent-listing.md) |
+| `docs/session-tree-plan.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/session-tree-plan.md) |
+| `docs/session.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/session.md) |
+| `docs/settings.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/settings.md) |
+| `docs/skills.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills.md) |
+| `docs/skills/authoring-extensions.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills/authoring-extensions.md) |
+| `docs/skills/authoring-hooks.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills/authoring-hooks.md) |
+| `docs/skills/authoring-marketplaces.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills/authoring-marketplaces.md) |
+| `docs/skills/examples/hello-extension/README.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills/examples/hello-extension/README.md) |
+| `docs/skills/examples/mini-marketplace/README.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills/examples/mini-marketplace/README.md) |
+| `docs/skills/examples/safety-hook/README.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/skills/examples/safety-hook/README.md) |
+| `docs/slash-command-internals.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/slash-command-internals.md) |
+| `docs/system-prompt-customization.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/system-prompt-customization.md) |
+| `docs/task-agent-discovery.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/task-agent-discovery.md) |
+| `docs/theme.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/theme.md) |
+| `docs/toolconv/anthropic.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/anthropic.md) |
+| `docs/toolconv/deepseek.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/deepseek.md) |
+| `docs/toolconv/gemini.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/gemini.md) |
+| `docs/toolconv/gemma.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/gemma.md) |
+| `docs/toolconv/glm-4.5.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/glm-4.5.md) |
+| `docs/toolconv/harmony.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/harmony.md) |
+| `docs/toolconv/hermes.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/hermes.md) |
+| `docs/toolconv/kimi-k2.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/kimi-k2.md) |
+| `docs/toolconv/minimax.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/minimax.md) |
+| `docs/toolconv/pi-native.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/pi-native.md) |
+| `docs/toolconv/qwen3.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/qwen3.md) |
+| `docs/toolconv/xml.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/toolconv/xml.md) |
+| `docs/tools/ask.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/ask.md) |
+| `docs/tools/ast-edit.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/ast-edit.md) |
+| `docs/tools/ast-grep.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/ast-grep.md) |
+| `docs/tools/bash.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/bash.md) |
+| `docs/tools/browser.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/browser.md) |
+| `docs/tools/checkpoint.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/checkpoint.md) |
+| `docs/tools/computer.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/computer.md) |
+| `docs/tools/context-notes.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/context-notes.md) |
+| `docs/tools/debug.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/debug.md) |
+| `docs/tools/edit.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/edit.md) |
+| `docs/tools/eval.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/eval.md) |
+| `docs/tools/generate_image.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/generate_image.md) |
+| `docs/tools/github.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/github.md) |
+| `docs/tools/glob.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/glob.md) |
+| `docs/tools/grep.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/grep.md) |
+| `docs/tools/hub.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/hub.md) |
+| `docs/tools/learn.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/learn.md) |
+| `docs/tools/lsp.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/lsp.md) |
+| `docs/tools/manage_skill.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/manage_skill.md) |
+| `docs/tools/memory_edit.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/memory_edit.md) |
+| `docs/tools/new-context.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/new-context.md) |
+| `docs/tools/read.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/read.md) |
+| `docs/tools/recall.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/recall.md) |
+| `docs/tools/reflect.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/reflect.md) |
+| `docs/tools/retain.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/retain.md) |
+| `docs/tools/rewind.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/rewind.md) |
+| `docs/tools/security_scan.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/security_scan.md) |
+| `docs/tools/task.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/task.md) |
+| `docs/tools/todo.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/todo.md) |
+| `docs/tools/tts.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/tts.md) |
+| `docs/tools/web_search.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/web_search.md) |
+| `docs/tools/write.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tools/write.md) |
+| `docs/tree.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tree.md) |
+| `docs/ttsr-injection-lifecycle.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/ttsr-injection-lifecycle.md) |
+| `docs/tui-core-renderer.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tui-core-renderer.md) |
+| `docs/tui-runtime-internals.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tui-runtime-internals.md) |
+| `docs/tui.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/tui.md) |
+| `docs/user-facing-packages.md` | reviewed-ranges | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/user-facing-packages.md) |
+| `docs/vibe-mode.md` | indexed-not-individually-audited | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/docs/vibe-mode.md) |
+
+## Additional source-level contracts
+
+| Path | Pinned source |
+| --- | --- |
+| `packages/coding-agent/src/config/model-roles.ts` | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/config/model-roles.ts) |
+| `packages/coding-agent/src/config/model-resolver.ts` | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/config/model-resolver.ts) |
+| `packages/coding-agent/test/model-resolver.test.ts` | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/test/model-resolver.test.ts) |
+| `packages/coding-agent/src/task/structured-subagent.ts` | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/task/structured-subagent.ts) |
+| `packages/coding-agent/src/eval/workpool-bridge.ts` | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/src/eval/workpool-bridge.ts) |
+| `packages/coding-agent/package.json` | [Source](https://github.com/can1357/oh-my-pi/blob/dbf3afad4894bde827d90f965e77b3fe1c5a95e5/packages/coding-agent/package.json) |
+
+For a package-local feature not covered by root docs, follow `user-facing-packages.md` into the corresponding README and manifest. Retrieve and record those additional files at the same commit; this index does not certify their contents.

package/skills/omp-native-development/references/offline-test-results.txt

@@ -0,0 +1,43 @@
+Executed offline utility suite; not native OMP tests.
+
+test_atomic_no_overwrite (test_tools.CorpusTests.test_atomic_no_overwrite) ... ok
+test_bad_repository_rejected (test_tools.CorpusTests.test_bad_repository_rejected) ... ok
+test_cli_search_read_and_partial_failure (test_tools.CorpusTests.test_cli_search_read_and_partial_failure) ... ok
+test_duplicate_manifest_entry_rejected (test_tools.CorpusTests.test_duplicate_manifest_entry_rejected) ... ok
+test_git_blob_format (test_tools.CorpusTests.test_git_blob_format) ... ok
+test_html_and_corruption_rejected (test_tools.CorpusTests.test_html_and_corruption_rejected) ... ok
+test_local_git_end_to_end_and_drift (test_tools.CorpusTests.test_local_git_end_to_end_and_drift) ... ok
+test_manifest_loaded (test_tools.CorpusTests.test_manifest_loaded) ... ok
+test_missing_corpus_not_complete (test_tools.CorpusTests.test_missing_corpus_not_complete) ... ok
+test_mock_http_happy_path (test_tools.CorpusTests.test_mock_http_happy_path) ... ok
+test_mock_http_timeout (test_tools.CorpusTests.test_mock_http_timeout) ... ok
+test_mock_http_wrong_hash (test_tools.CorpusTests.test_mock_http_wrong_hash) ... ok
+test_moving_branch_pin_rejected (test_tools.CorpusTests.test_moving_branch_pin_rejected) ... ok
+test_path_traversal_rejected (test_tools.CorpusTests.test_path_traversal_rejected) ... ok
+test_symlink_rejected (test_tools.CorpusTests.test_symlink_rejected) ... ok
+test_sync_and_verify (test_tools.CorpusTests.test_sync_and_verify) ... ok
+test_actual_config_list_shape (test_tools.RoleAuditTests.test_actual_config_list_shape) ... ok
+test_advisor_configured_role (test_tools.RoleAuditTests.test_advisor_configured_role) ... ok
+test_bad_record_and_bad_storage (test_tools.RoleAuditTests.test_bad_record_and_bad_storage) ... ok
+test_builtin_does_not_need_mapping (test_tools.RoleAuditTests.test_builtin_does_not_need_mapping) ... ok
+test_credentials_not_echoed (test_tools.RoleAuditTests.test_credentials_not_echoed) ... ok
+test_cycle_is_explicitly_bizar_policy (test_tools.RoleAuditTests.test_cycle_is_explicitly_bizar_policy) ... ok
+test_dotted_settings (test_tools.RoleAuditTests.test_dotted_settings) ... ok
+test_exact_agent_names (test_tools.RoleAuditTests.test_exact_agent_names) ... ok
+test_legacy_alias_warning_not_error (test_tools.RoleAuditTests.test_legacy_alias_warning_not_error) ... ok
+test_model_colons_and_routes_not_misparsed_as_roles (test_tools.RoleAuditTests.test_model_colons_and_routes_not_misparsed_as_roles) ... ok
+test_nested_role_profile (test_tools.RoleAuditTests.test_nested_role_profile) ... ok
+test_outer_role_effort (test_tools.RoleAuditTests.test_outer_role_effort) ... ok
+test_prewalk_requires_quoted_string (test_tools.RoleAuditTests.test_prewalk_requires_quoted_string) ... ok
+test_redacted_metadata (test_tools.RoleAuditTests.test_redacted_metadata) ... ok
+test_required_role_missing (test_tools.RoleAuditTests.test_required_role_missing) ... ok
+test_self_cycle (test_tools.RoleAuditTests.test_self_cycle) ... ok
+test_service_tier_not_effort (test_tools.RoleAuditTests.test_service_tier_not_effort) ... ok
+test_template_placeholder_rejected (test_tools.RoleAuditTests.test_template_placeholder_rejected) ... ok
+test_unknown_role_alias (test_tools.RoleAuditTests.test_unknown_role_alias) ... ok
+test_valid_tier_still_not_native_qualified (test_tools.RoleAuditTests.test_valid_tier_still_not_native_qualified) ... ok
+
+----------------------------------------------------------------------
+Ran 36 tests in 0.051s
+
+OK

package/skills/omp-native-development/references/research-and-test-status.md

@@ -0,0 +1,31 @@
+# Research and test status
+
+Created 2026-09-17 for the BizarHarness OMP-native rewrite.
+
+## Research scope
+
+The research baseline is the actual GitHub main reference `dbf3afad4894bde827d90f965e77b3fe1c5a95e5`. The complete enumerated root docs tree contained 131 Markdown documents. All are indexed with immutable paths and Git blob hashes. Six selected source/package/test files are also pinned, for 137 fetchable entries.
+
+The core native role, configuration, extension, task and SDK contracts were reviewed through official repository documents and selected source paths across the rewrite research and this skill task. The source manifest distinguishes reviewed ranges from documents that were indexed but not individually audited. Some supporting documents are linked for further targeted investigation; a link is not a claim that their whole contents were reviewed.
+
+Full upstream text is not bundled. The artifact-building container had no working network/DNS, although the GitHub connector could retrieve source text for research. The included fetch utility populates a verified reference corpus in an online development environment or from a local Git checkout. Package-local READMEs, every test and every source file are outside the exhaustive index scope; follow the document/source references when needed.
+
+## Tests actually executed
+
+The standard-library Python utilities passed 36 offline unit tests. These cover effective native config JSON shape, nested/dotted profile access, role requirements, aliases, cycle diagnostics, exact agent names, placeholder detection, secret non-disclosure, service-tier shape, malformed input, Git blob hashing, unsafe paths and symlinks, missing/corrupt corpus detection, no-overwrite writes, mocked HTTP success/hash failure/timeout, read/search CLI behavior, and local Git extraction/drift end to end.
+
+HTTP tests use controlled mocks. They do not claim a successful live network fetch in this container. The local Git fixture test actually creates a temporary repository, commits known content, extracts the pinned object, advances HEAD and verifies detected drift without changing the extracted corpus.
+
+Both TypeScript assets passed syntax-only transpilation with TypeScript 5.8.3. This did not resolve native dependencies or type-check the OMP APIs.
+
+The final package is checked for valid skill frontmatter, expected structure, internal authored links, parsable JSON/YAML examples, archive integrity, absence of template placeholders in the skill instructions, and presence of all referenced assets. See `bundle-validation.json` for the final artifact check results.
+
+## Not executed here
+
+Bun was not installed in the artifact-building environment. Therefore the 17 native helper test cases in the supplied TypeScript starter suite were NOT RUN. The native role-probe extension was source-reviewed but not loaded into OMP here. Neither TypeScript native dependency compatibility nor model-backed child execution was established by the Python suite.
+
+The acceptance matrix contains proposed native/Bizar qualification scenarios, initially all NOT RUN. No provider credentials, live OmniRoute configuration, remote endpoints, agent loops, TUI behavior, isolation backend or end-to-end Bizar workflow were exercised. The original repository was not modified or pushed.
+
+## Interpretation
+
+A passing utility test proves that utility behavior under its fixture, not that every claim about OMP is correct. A matching source hash proves byte identity, not semantic correctness. A configured role proves a configuration entry, not a working provider. This skill requires the developer to close those gaps with exact-target source inspection and execution evidence before asserting release readiness.