thehood 0.1.0-preview.0

package/docs/CODEX_SETUP.md

@@ -0,0 +1,288 @@
+# Codex Setup
+
+TheHood is exposed to Codex through its MCP server.
+
+## Build
+
+```bash
+npm install
+npm run build
+node dist/cli/main.js setup --repo .
+```
+
+`setup` is read-only. It prints the local-build command, a temporary shell alias, optional `npm link` guidance, MCP config commands, and TUI launch commands for the current checkout.
+
+## Get MCP Config
+
+For an installed package:
+
+```bash
+thehood mcp config
+```
+
+For this local checkout:
+
+```bash
+node dist/cli/main.js mcp config
+```
+
+The command prints two TOML snippets:
+
+- installed package: `command = "thehood"`
+- local build: `command = "node"` with the absolute path to `dist/cli/main.js`
+
+Use one snippet in Codex's MCP server configuration.
+
+## ChatGPT MCP Connector Mode
+
+This path is for ChatGPT Web/Pro acting as an MCP host. It is not the `chatgpt-web` browser bridge that Codex can ask TheHood to invoke.
+
+Generate deterministic Secure MCP Tunnel guidance for both installed and local-build commands:
+
+```bash
+thehood mcp tunnel --tunnel-id <tunnel-id> --profile thehood-local
+node dist/cli/main.js mcp tunnel --tunnel-id <tunnel-id> --profile thehood-local
+```
+
+Use the local-build command while developing this checkout so ChatGPT reaches the current `dist/cli/main.js`. The helper does not start the tunnel, install `tunnel-client`, configure ChatGPT, or contact OpenAI; it only prints the command shape TheHood expects.
+
+After running `tunnel-client init`, `tunnel-client doctor --profile thehood-local --explain`, and `tunnel-client run --profile thehood-local`, create the ChatGPT connector from the tunnel connection and enable it in a new ChatGPT conversation.
+
+First connector validation from ChatGPT:
+
+1. Ask ChatGPT to call `thehood_doctor` for the target `repo_path`.
+2. Ask ChatGPT to call `thehood_repo_tree` or `thehood_repo_read_file` for a harmless path.
+3. Ask ChatGPT to call `thehood_pro_access` when it needs the Pro bridge readiness and connector-mode handoff options.
+
+TheHood remains the local runtime and repo gateway in connector mode. ChatGPT receives only bounded tool results it calls, and private repos should use trusted MCP hosts because repo and run data can be disclosed through those results.
+
+For ChatGPT Pro through the included browser bridge, start the TheHood-managed browser profile and select the intended model:
+
+```bash
+node dist/cli/main.js browser start
+node dist/cli/main.js browser status
+```
+
+The browser manager uses a persistent isolated Chrome profile under `~/Library/Application Support/TheHood/ChromeProfiles/chatgpt-web` on macOS. The user signs into ChatGPT in that profile once; TheHood does not copy cookies, local storage, or tokens.
+
+Then use the opt-in config generator:
+
+```bash
+node dist/cli/main.js mcp config --chatgpt-web
+```
+
+This adds:
+
+- `THEHOOD_CHATGPT_WEB_COMMAND`
+- `THEHOOD_CHATGPT_WEB_MODEL_CONFIRMED=1`
+- `THEHOOD_CHATGPT_WEB_CDP_URL=http://127.0.0.1:9222`
+- `THEHOOD_CHATGPT_WEB_TIMEOUT_MS=600000`
+- `THEHOOD_CHATGPT_WEB_KEEP_TARGET_ON_FAILURE=1`
+
+Use `--cdp-url <url>` if Chrome is listening on a different DevTools endpoint.
+
+Before starting the Codex app, check the local bridge readiness:
+
+```bash
+node dist/cli/main.js doctor --repo /path/to/repo --json
+npm run smoke:codex-config -- --config ~/.codex/config.toml --repo /path/to/repo
+```
+
+For `chatgpt-web`, `doctor` verifies that the bridge command is configured and executable, the model confirmation guard is enabled, Chrome DevTools is reachable, a ChatGPT tab is visible, the page is authenticated, and the composer is ready. Common issues are `bridge_command_not_configured`, `model_not_confirmed`, `cdp_unreachable`, `chatgpt_tab_not_found`, `chatgpt_auth_required`, `chatgpt_composer_not_ready`, and `chatgpt_page_uninspectable`.
+
+For `codex-cli`, `doctor` asks the installed Codex CLI for its current model catalog with `codex debug models`. TheHood keeps only sanitized model metadata, resolves friendly assignments such as `codex-cli:spark` against that live catalog, and reports `model_not_available:<model>` when a custom role assignment is not supported by the current CLI/account.
+
+## Actual Codex App Verification
+
+Add one generated TOML snippet to Codex's `config.toml`, then restart Codex so the MCP server list is rebuilt. A running Codex session should not be treated as proof because MCP servers are loaded at app or session startup.
+
+After restart, the TheHood server should expose these tools:
+
+- `thehood_doctor`
+- `thehood_roles`
+- `thehood_model_access`
+- `thehood_pro_access`
+- `thehood_recommend_loop`
+- `thehood_agent_board`
+- `thehood_assign_roles`
+- `thehood_plan`
+- `thehood_orchestrate`
+- `thehood_consult`
+- `thehood_summon`
+- `thehood_fanout`
+- `thehood_continue`
+- `thehood_loop`
+- `thehood_reconcile`
+- `thehood_status`
+- `thehood_runs`
+- `thehood_read_artifact`
+- `thehood_capture_evidence`
+- `thehood_abort`
+
+When developing TheHood itself, rebuild and restart the Codex app or MCP session before validating newly changed tool output. Existing Codex chats can keep an already-started MCP server process alive, so code changes may pass `smoke:codex-config` while the current chat still shows the previous tool behavior.
+
+Use `thehood_doctor` as the in-chat stale-server check. Current builds report `runtime.capabilities`; if Codex does not show expected capabilities such as `structured_mcp_next_actions`, `approval_artifact_next_actions`, `protected_integrated_patch_gate`, `cli_artifact_reads`, `approval_phrase_enforcement`, `final_report_artifacts`, `mcp_final_report_next_action`, `canonical_memory_rehydration`, `provider_directive_ack`, `local_agent_execution_artifacts`, `max_iteration_enforcement`, `validation_command_capture`, `review_routing_policy`, `chatgpt_browser_manager`, `chatgpt_web_bridge_fail_fast`, `chatgpt_web_session_isolation`, `chatgpt_web_auth_readiness`, `branded_tui_shell`, `operator_next_actions`, `loop_responsibility_schedule`, `crew_lane_trail`, `revision_trail`, `runtime_loop_runner`, `autopilot_approval_policy`, `mcp_autopilot_continue_guidance`, `run_status_insights`, `same_run_agent_summons`, `bounded_same_run_fanout`, `runtime_team_presets`, `multi_model_team_presets`, `loop_recommendation_router`, `codex_loop_plan_artifact`, `provider_model_passthrough`, `configurable_budget_envelopes`, `model_assisted_qa_tester`, `critic_trigger_artifacts`, `pro_access_preflight`, `model_access_preflight`, `codex_agent_board`, and `codex_agent_board_artifact`, the chat is still connected to an older MCP server process.
+
+Codex can recommend a loop shape before starting work by calling `thehood_recommend_loop`. The tool is read-only and returns a recommended recipe, recommended stack, draft completion contract, alternatives, editable card actions, renderer-facing `card`, `runAction`, and dashboard payload for a loop-plan card. Recommendation does not call providers, edit files, approve gates, or start schedules; accepting the card should invoke the returned runtime action.
+
+When developing locally, build the runtime and run `npm run smoke:codex-config` to verify a fresh MCP launch exposes current tools. Existing Codex conversations may keep a previously loaded tool schema; if the smoke passes but the current thread does not show `thehood_recommend_loop`, start a new Codex thread or reload the Codex app/session so it reconnects to TheHood.
+
+Codex can request renderable agent visibility by calling `thehood_agent_board` with `include_artifact: true`. The returned `artifact.manifest` and `artifact.snapshot` are dashboard payloads derived from runtime state and can be passed to an available Codex artifact renderer. Rendering remains a display layer: it does not schedule agents, approve gates, or grant tools.
+
+Codex can inspect the general model-access path by calling `thehood_model_access`. This is a local-only preflight: it does not call Claude, Codex CLI, ChatGPT, or API providers and does not send repo context externally. Use it before external model-backed consults or fan-outs that may disclose repo context, progress packets, memory, or runtime artifacts. Dirty or unpushed repos should show the user choices returned by the preflight: commit and push a checkpoint, approve bounded local context/diff transfer, use no-repo-context strategy, or cancel. Clean pushed GitHub repos should default to remote refs only when the preflight reports the provider route as confirmed; for `chatgpt-web`, unconfirmed bridge GitHub connector access still requires user choice. If host policy blocks the direct call, present the returned compact approval packet with `approval_packet.copyable_text_block` as a fenced `text` block, or switch to no-repo-context or connector mode.
+
+Codex can inspect the Pro access path by calling `thehood_pro_access`. This is a local-only preflight: it does not call ChatGPT Pro and does not send repo context externally. Use it when a direct `chatgpt-web` consult is rejected by Codex host policy, when bridge readiness is unclear, or when the right answer is to switch to ChatGPT MCP connector mode instead of asking for the same approval again.
+
+First verification sequence from a Codex chat:
+
+1. Call `thehood_doctor` for the target repo and confirm active roles have no issues.
+2. Call `thehood_roles` or `thehood_agent_board` and confirm the agent roster shows the intended orchestrator, implementer, QA, verifier, and critic owners.
+3. Call `thehood_model_access` before external model-backed consults or fan-outs that may disclose repo context, progress packets, memory, or runtime artifacts. If the repo is dirty or unpushed, show the returned user choices. If the repo is clean and pushed, use the remote GitHub refs default only when the preflight reports the provider route as confirmed. If Codex host policy blocks external disclosure, use the returned compact approval packet and show `approval_packet.copyable_text_block` in a fenced `text` block, or switch to no-repo-context or connector mode.
+4. Call `thehood_pro_access` before direct Pro consults from Codex when ChatGPT Web bridge readiness or connector-mode handoff details matter.
+5. Call `thehood_plan` for a harmless read-only goal.
+6. Call `thehood_continue` with `approval: "none"` for that run. In manual mode, confirm it stops for explicit approval before invoking the configured read-only provider, which is Codex CLI by default. In autopilot mode, confirm provider invocation is auto-approved and recorded as `approval_auto_approved`.
+7. Approve a provider invocation only when a manual approval gate is active and the user accepts calling the configured provider for the repo, then continue the run and confirm it returns schema-valid JSON.
+8. If a ChatGPT Web or API provider is configured and delegates repo inspection, confirm the runtime creates a bounded `context` artifact. In manual mode it should stop for explicit approval before sending that context back to the provider; in autopilot or auto-low-risk transfer mode it may auto-approve a bounded non-secret manifest and record the transfer approval.
+9. Approve the context transfer only when a manual transfer gate is active and the user accepts sending bounded repo evidence, then continue the run.
+10. For implementation testing, call `thehood_orchestrate` in `implement` mode and confirm it stops for approval before edit-capable execution.
+
+## Optional Codex Plugin
+
+The repo includes an optional Codex plugin scaffold at `plugins/thehood-codex` and a repo-local marketplace at `.agents/plugins/marketplace.json`.
+
+Install it only when you want Codex to load TheHood-specific workflow guidance and MCP wiring:
+
+```bash
+codex plugin marketplace add /path/to/the-hood
+codex plugin add thehood-codex@thehood
+```
+
+Start a new Codex thread after installing or updating the plugin so Codex reloads plugin skills and MCP configuration.
+
+The plugin's MCP server config runs `thehood mcp`, so the `thehood` binary must be available on `PATH`. For local development, either link/install the package after `npm run build` or keep using the explicit local snippet from:
+
+```bash
+node dist/cli/main.js mcp config
+```
+
+## Native Codex Subagents
+
+Codex's native Subagents panel is owned by Codex subagent workflows, not by MCP tool output. TheHood cannot directly register an arbitrary running provider call into that panel through `thehood_agent_board` or another MCP tool.
+
+This repository does not include repo-root `.codex/agents/` custom agents by default because those agents make Codex show a native Subagents surface even when the user did not ask for it.
+
+If a future TheHood plugin version offers opt-in custom agents, use them only when the user explicitly wants Codex-native subagent threads. For example:
+
+```text
+Use TheHood native subagents for this review. Spawn thehood-qa and thehood-critic in parallel, wait for both, and summarize their findings with file references.
+```
+
+Those spawned Codex agents should appear in the native Codex Subagents panel. They inherit the parent session's model, MCP servers, sandbox, and approvals unless Codex is told otherwise. Any custom agents are presentation and delegation helpers for Codex-native workflows; TheHood runtime state, artifacts, approvals, and verifier separation remain authoritative.
+
+Use `thehood_agent_board` with `include_artifact: true` when you want TheHood runtime-owned role visibility rendered as an in-chat dashboard instead of native Codex subagent threads.
+
+## Recommended First Codex Chat
+
+After Codex can see TheHood tools:
+
+1. Ask Codex to call `thehood_doctor` for the repo.
+2. Ask Codex to call `thehood_agent_board` and inspect the visible agent cards before changing any role owner.
+3. Ask Codex to call `thehood_model_access` before Claude/Codex/GPT/Pro consults or fan-outs that may disclose repo context, progress packets, memory, or runtime artifacts. If the repo is dirty or unpushed, show the returned choices. If the repo is clean and pushed, use the remote GitHub refs default only when the preflight reports the provider route as confirmed. If Codex host policy rejects direct external disclosure, use the returned compact approval packet, show `approval_packet.copyable_text_block` in a fenced `text` block, or use no-repo-context fallback / connector-mode handoff instead of repeating a long custom approval sentence.
+4. Ask Codex to call `thehood_pro_access` before direct ChatGPT Pro consults when you need ChatGPT Web bridge readiness or ChatGPT MCP connector handoff details.
+5. Ask Codex to call `thehood_consult` or `thehood_fanout` with read-only guest roles. When no manual gate is active, Codex should continue with `approval: "none"` and let TheHood autopilot auto-approve bounded provider gates when policy allows.
+6. Use `thehood_orchestrate` for implementation work.
+7. Use `thehood_continue` with explicit approval only for active manual approval gates.
+
+Example guest critic:
+
+```json
+{
+  "goal": "Critique this implementation plan before code changes.",
+  "repo_path": "/path/to/repo",
+  "role": "critic",
+  "agent": "codex-cli:spark"
+}
+```
+
+Example QA tester:
+
+```json
+{
+  "goal": "Review the current evidence and suggest missing validation commands.",
+  "repo_path": "/path/to/repo",
+  "role": "qa",
+  "agent": "codex-cli:spark"
+}
+```
+
+Example ChatGPT Pro orchestrator consult:
+
+```json
+{
+  "goal": "Plan the safest implementation path before workers start.",
+  "repo_path": "/path/to/repo",
+  "role": "orchestrator",
+  "agent": "chatgpt-web:chatgpt-pro"
+}
+```
+
+`chatgpt-web` requires a local bridge executable:
+
+```bash
+export THEHOOD_CHATGPT_WEB_COMMAND=/path/to/chatgpt-web-bridge
+```
+
+The bridge receives the TheHood prompt on stdin, gets `--model <model>` and `--schema <schema-path>` arguments, uses the user's authenticated ChatGPT session, and prints the normalized `AgentResponse` JSON envelope to stdout. The JSON envelope is for mechanical fields; long plans, reports, and rationale should be returned as markdown in the role payload's `markdown` string. TheHood intentionally does not read ChatGPT cookies, browser local storage, or tokens.
+
+This package includes an experimental Chrome DevTools bridge:
+
+```bash
+npm run build
+export THEHOOD_CHATGPT_WEB_COMMAND=/path/to/thehood/dist/bridges/chatgptWebBridge.js
+```
+
+Start the TheHood-managed browser profile, open ChatGPT, sign in if needed, and select the model you want the bridge to use:
+
+```bash
+node dist/cli/main.js browser start
+```
+
+After you have visibly selected the intended model in ChatGPT, enable the model confirmation guard:
+
+```bash
+export THEHOOD_CHATGPT_WEB_MODEL_CONFIRMED=1
+```
+
+Optional bridge settings:
+
+```bash
+export THEHOOD_CHATGPT_WEB_CDP_URL=http://127.0.0.1:9222
+export THEHOOD_CHATGPT_WEB_FRESH_URL=https://chatgpt.com/
+export THEHOOD_CHATGPT_WEB_TIMEOUT_MS=600000
+export THEHOOD_CHATGPT_WEB_PROMPT_SELECTOR="#prompt-textarea,[contenteditable='true'],textarea"
+export THEHOOD_CHATGPT_WEB_SEND_SELECTOR="button[data-testid='send-button'],button[aria-label*='Send'],button[aria-label*='send']"
+export THEHOOD_CHATGPT_WEB_RESPONSE_SELECTOR="[data-message-author-role='assistant']"
+export THEHOOD_CHATGPT_WEB_NEW_CHAT_SELECTOR="a[href='/'],button[aria-label*='New chat']"
+export THEHOOD_CHATGPT_WEB_RUN_SCOPED_TARGETS=1
+# export THEHOOD_CHATGPT_WEB_REUSE_CHAT=1
+# export THEHOOD_CHATGPT_WEB_KEEP_TARGET=1
+# export THEHOOD_CHATGPT_WEB_KEEP_TARGET_ON_FAILURE=0
+```
+
+By default, TheHood runtime calls use one ChatGPT target per run. The first bridge call creates and verifies a fresh composer, then later ChatGPT Web calls in the same run reuse that target instead of opening a new chat after every Pro answer. The bridge still requires the visible response to echo the current `directiveAck` inside the role payload, so stale project or conversation context fails closed. Calls without a run id keep the older one-target-per-call lifecycle: close after a successfully parsed response, keep the target open when browser access, parsing, acknowledgement, or timeout handling fails. Set `THEHOOD_CHATGPT_WEB_REUSE_CHAT=1` only when intentionally debugging against the current conversation, set `THEHOOD_CHATGPT_WEB_RUN_SCOPED_TARGETS=0` to disable run-scoped target reuse, and set `THEHOOD_CHATGPT_WEB_KEEP_TARGET_ON_FAILURE=0` only when you want failed bridge calls to clean up their temporary tabs.
+
+Example persistent role assignment:
+
+```json
+{
+  "repo_path": "/path/to/repo",
+  "role_mapping": {
+    "orchestrator": "codex-cli:default",
+    "qa": "codex-cli:spark",
+    "critic": "codex-cli:spark",
+    "verifier": "codex-cli:spark"
+  }
+}
+```
+
+The implementer and verifier must still be separate assignments.

package/docs/COMPLETION_CONTRACT.md

@@ -0,0 +1,52 @@
+# Completion Contract
+
+A completion contract is the pre-work definition of done for a TheHood goal loop. It turns "keep working until good" into a bounded, reviewable target.
+
+## Contract Fields
+
+| Field | Meaning |
+| --- | --- |
+| Goal | The concrete outcome the run should achieve. |
+| Acceptance criteria | Conditions that must be true before completion. |
+| Allowed paths | Files or directories the implementer may change. |
+| Forbidden changes | Changes that must stop the run or require separate approval. |
+| Validation | Commands or evidence required before verifier review. |
+| Stop condition | When the loop should stop even if the model wants to continue. |
+| Iteration budget | Maximum provider/repair attempts before fail-closed behavior. |
+| Required evidence | Artifact classes the final report must reference. |
+
+## Example
+
+```yaml
+goal: Prepare npm preview package metadata.
+allowed_paths:
+  - package.json
+  - package-lock.json
+  - docs/NPM_PUBLISHING.md
+forbidden_changes:
+  - npm publish
+  - npm token or secret files
+  - hosted backend code
+acceptance_criteria:
+  - package version is 0.1.0-preview.0
+  - release:check exists and uses existing smoke commands
+  - npm pack dry-run succeeds
+validation:
+  - npm run typecheck
+  - npm run build
+  - npm run smoke:mcp
+  - npm run smoke:codex-config
+  - npm run smoke:runtime
+  - npm pack --dry-run --json
+  - git --no-pager diff --check
+stop_condition: verifier approves or asks user to resolve a release boundary
+iteration_budget: 5
+required_evidence:
+  - package diff
+  - validation command logs
+  - final report
+```
+
+## Runtime Behavior
+
+The implementer can produce changes, but it cannot accept its own work. Completion requires runtime-captured evidence and independent verifier review when the run is an implementation run.

package/docs/CONTRIBUTOR_GUIDE.md

@@ -0,0 +1,70 @@
+# Contributor Guide
+
+TheHood is a local runtime for governed software agent loops. Public contributions should preserve the runtime trust model before adding new surfaces.
+
+## Local Setup
+
+```bash
+npm ci
+npm run build
+node dist/cli/main.js doctor --repo .
+node dist/cli/main.js roster --repo .
+```
+
+## Validation
+
+Run the smallest relevant checks while developing. Before release-sensitive changes, run:
+
+```bash
+npm run typecheck
+npm run build
+npm run smoke:mcp
+npm run smoke:codex-config
+npm run smoke:runtime
+git --no-pager diff --check
+```
+
+Use `npm run release:check` before packaging or release changes.
+
+## Forbidden Content
+
+Do not commit:
+
+- `.thehood/` runtime state
+- provider transcripts
+- browser profiles
+- cookies or session tokens
+- API keys
+- local `.env` files
+- private prompts
+- private repo data
+- generated package archives
+- real customer or payment data
+
+Examples, demos, fixtures, and screenshots must be synthetic or scrubbed.
+
+## Runtime Boundaries
+
+- Runtime logic belongs in `src/runtime`.
+- Provider adapters normalize external behavior into TheHood schemas.
+- CLI, MCP, TUI, website, and future app surfaces should trigger runtime actions, not duplicate orchestration policy.
+- Implementer and verifier must stay separate for implementation work.
+- Verifier, QA tester, critic, and researcher roles must not receive edit tools.
+- Protected test, fixture, snapshot, and eval changes require explicit classification and review.
+
+## Provider Changes
+
+Provider adapter proposals should explain:
+
+- provider mode
+- auth and secret storage
+- output schema mapping
+- approval gates
+- transfer manifests
+- fail-closed behavior
+- validation plan
+- docs updates
+
+## Docs Changes
+
+Docs should describe current state, not aspirational behavior. When a feature is planned or experimental, say so directly.

package/docs/DEMO.md

@@ -0,0 +1,62 @@
+# Synthetic Stub Demo
+
+This demo proves the public-preview loop without sending code or artifacts to an external provider.
+
+It uses only the deterministic `stub` provider, a temporary demo repository, local runtime state, and a package validation script that prints a fixed message.
+
+## Run The Demo From This Checkout
+
+Build TheHood first:
+
+```bash
+npm run build
+```
+
+Create a synthetic repository and give it a validation command:
+
+```bash
+DEMO_REPO="$(mktemp -d)"
+node dist/cli/main.js init --repo "$DEMO_REPO"
+node dist/cli/main.js approvals policy set mode autopilot --repo "$DEMO_REPO"
+cat > "$DEMO_REPO/package.json" <<'JSON'
+{
+  "scripts": {
+    "typecheck": "node -e \"process.stdout.write('demo validation ok\\n')\""
+  }
+}
+JSON
+```
+
+Run a bounded goal loop with stub roles:
+
+```bash
+node dist/cli/main.js goal "Synthetic demo: prove a governed local loop can complete" \
+  --repo "$DEMO_REPO" \
+  --orchestrator stub:orchestrator \
+  --implementer stub:implementer \
+  --qa stub:qa \
+  --verifier stub:verifier \
+  --critic stub:critic \
+  --max-iterations 5 \
+  --json
+```
+
+The run should complete locally and emit a JSON result with:
+
+- `run.state` set to `completed`
+- `run.mode` set to `implement`
+- `run.maxIterations` set to `5`
+- provider responses from the deterministic stub provider
+- runtime-owned approval events showing autopilot decisions
+
+Inspect the final state:
+
+```bash
+node dist/cli/main.js status --repo "$DEMO_REPO"
+```
+
+## Boundary
+
+This demo does not use ChatGPT Pro, Claude Code, Codex CLI, OpenAI API, Anthropic API, browser automation, the ChatGPT MCP connector, a hosted queue, a timer, or a cloud service.
+
+It is intentionally synthetic. Its purpose is to show the runtime loop, role separation, approval policy, artifacts, validation evidence, and terminal completion behavior without depending on external accounts or private repository contents.

package/docs/GLOSSARY.md

@@ -0,0 +1,46 @@
+# Glossary
+
+## Agent
+
+A model-backed or tool-backed participant with a role contract, input schema, permissions, and output schema.
+
+## Orchestrator
+
+The role that plans, delegates, compares evidence, and controls the loop.
+
+## Implementer
+
+The role that makes scoped code changes.
+
+## Verifier
+
+The role that evaluates changes using runtime-captured evidence. It has no edit tools.
+
+## Critic
+
+The role that challenges a plan or patch and identifies risk.
+
+## Runtime
+
+The local deterministic system that owns state, permissions, command execution, logs, worktrees, approvals, and integration.
+
+## Provider Adapter
+
+An integration layer that lets TheHood use a model or agent system through a common interface.
+
+## MCP Server
+
+The server that exposes TheHood runtime tools to Codex and other MCP clients.
+
+## Control Surface
+
+A user-facing way to trigger or inspect runtime actions. The CLI, MCP server, and macOS app are control surfaces.
+
+## Protected Path
+
+A file path that requires special approval before modification, such as tests, fixtures, snapshots, or evaluation files.
+
+## Evidence
+
+Runtime-captured material used for decisions, such as diffs, logs, exit codes, and file reads.
+

package/docs/GOAL_LOOP_SCHEDULE.md

@@ -0,0 +1,50 @@
+# Goal, Loop, Schedule
+
+TheHood `v0.1.0-preview.0` is about governed software goals and bounded local loops. It is not yet a scheduling product.
+
+## Goal
+
+A goal is a concrete software objective with a verifiable stop condition.
+
+Examples:
+
+- "Prepare npm preview release metadata and prove package dry-run succeeds."
+- "Add a synthetic stub demo and verify it does not call external providers."
+- "Fix a failing smoke test and capture validation evidence."
+
+A good goal includes:
+
+- acceptance criteria
+- allowed paths
+- forbidden changes
+- validation commands
+- iteration budget
+- stop condition
+
+## Loop
+
+A loop is a runtime-owned sequence that keeps advancing a run until a terminal state, manual gate, no progress, or a budget cap.
+
+Loops can plan, delegate, capture evidence, verify, revise, and stop. They are local-session workflows. If the local process stops, the run record remains, but TheHood is not a hosted daemon.
+
+## Schedule
+
+A schedule is a future routine that runs later or repeatedly from a daemon or hosted service.
+
+Schedules are not part of `v0.1.0-preview.0`. The preview should not claim cloud routines, timer loops, overnight PR repair, or post-commit automation as current behavior.
+
+## Product Boundary
+
+For the preview:
+
+- `goal` is in scope.
+- `loop` is in scope while the local runtime is active.
+- `schedule` is future work.
+
+The CLI goal surface is intentionally thin:
+
+```bash
+thehood goal "Prepare release metadata" --repo . --max-iterations 5
+```
+
+It creates a normal implementation run and drives the existing headless loop. It does not add timers, background daemons, cloud queues, or new approval semantics.

package/docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,29 @@
+# Known Limitations
+
+TheHood `v0.1.0-preview.0` is a developer preview. It is meant to prove a local governed software goal-loop runtime, not the full long-term product.
+
+## Not Built Yet
+
+- No hosted runtime backend.
+- No cloud routines, cron schedules, or overnight hosted automation.
+- No timer-based `thehood schedule` surface.
+- No full hosted web dashboard.
+- No production OpenAI API adapter.
+- No production Anthropic API adapter.
+- No production local model adapter.
+- No built-in TheHood loop preset marketplace. The preview can recommend local recipe shapes, but it does not yet import or publish third-party loop catalogs as executable runtime presets.
+- No polished macOS menubar app.
+- No automatic native Codex visual rendering beyond explicit agent-board or dashboard artifact payloads.
+
+## Experimental Surfaces
+
+- ChatGPT Web bridge depends on a user-authenticated browser session and can break when ChatGPT UI behavior changes.
+- ChatGPT MCP connector mode depends on custom connector/tunnel availability in the user's ChatGPT workspace.
+- Local Codex CLI and Claude Code adapters depend on locally installed tools and their own provider access.
+- The optional Codex plugin is an opt-in workflow helper, not a runtime authority.
+
+## Operational Limits
+
+- The runtime is local-first. If the machine sleeps, network access disappears, or the terminal session stops, local runs can stop.
+- TheHood preserves evidence and artifacts, but users must still review private data before publishing a repo.
+- The deterministic runtime can enforce local gates, but it cannot bypass Codex, ChatGPT, Claude, tenant, GitHub, or npm policy gates.

package/docs/LICENSING.md

@@ -0,0 +1,21 @@
+# Licensing
+
+TheHood is licensed under the MIT License.
+
+## Why MIT
+
+MIT is the right fit for TheHood's current public posture:
+
+- it is familiar to the JavaScript and developer-tooling ecosystem
+- it is short, permissive, and easy to understand
+- it lowers adoption friction for early users, forks, and experiments
+- it gives the public repo a more approachable signal while the runtime is still young
+
+## Tradeoff
+
+Apache-2.0 remains a reasonable future option for projects that need an explicit patent grant and more formal contribution posture. TheHood is choosing MIT for reputation, simplicity, and adoption at this stage.
+
+## Files
+
+- Root license file: `LICENSE`
+- Package metadata: `package.json` uses SPDX id `MIT`