@humain/terminal 0.0.1

package/docs/humain-code-forge-flow-walkthrough.md

@@ -0,0 +1,414 @@
+# HUMAIN Code / Forge Flow Walkthrough
+
+This page describes the current HUMAIN Code and Forge data flow in HUMAIN Terminal. It is a descriptive
+walkthrough of how the repo behaves today, including the parts that are not ideal. The normative architecture
+contract remains [HUMAIN Code / Forge Architecture](humain-code-forge-architecture.md).
+The scored implementation audit lives in the
+[HUMAIN Code / Forge Component Scorecard](humain-code-forge-component-scorecard.md).
+
+Use this page when you need to understand the layers before changing Forge startup behavior, DeployNow model
+bindings, provider registration, workflow model selection, request auth, or startup cwd handling.
+
+## How To Read This
+
+Start from the data path, then compare it to the architecture contract:
+
+1. Startup selects the effective cwd and injects HUMAIN defaults.
+2. Resource loading discovers extensions, skills, prompts, themes, context files, and pending provider
+   registrations.
+3. The bundled HUMAIN extension interprets Forge and DeployNow descriptors and registers providers.
+4. The model registry turns provider registrations into model availability and request auth.
+5. Normal `/login`, `/model`, session restoration, and workflow configuration determine the selected model.
+6. `packages/ai` owns the provider-specific transport.
+
+## System Map
+
+```text
+CLI/env/settings
+  -> main.ts resolves startup cwd
+  -> main.ts injects HUMAIN extension factories and default package sources
+  -> DefaultResourceLoader loads packages, extensions, skills, prompts, themes, and context files
+  -> createAgentSessionServices flushes extension provider registrations into ModelRegistry
+  -> createAgentSession builds Agent + AgentSession
+  -> AgentSession binds ExtensionRunner actions to session/model/tool operations
+  -> /login supplies supported credentials and /model selects a registered model
+  -> dynamic-workflows applies its own model selection without HUMAIN routing
+  -> AgentSession streamFn asks ModelRegistry for apiKey/headers/env
+  -> packages/ai streams through OpenAI, Anthropic, Bedrock, or another registered provider
+  -> AgentSession persists events and updates interactive/RPC/print surfaces
+```
+
+## Layer Responsibilities
+
+| Layer | Current responsibility in this flow |
+| --- | --- |
+| `packages/coding-agent/src/main.ts` | CLI startup, cwd resolution, app mode selection, runtime factory construction, HUMAIN extension injection. |
+| `packages/coding-agent/src/core` | Settings, auth storage, model registry, resource loading, extension runtime, sessions, tools, request auth assembly. |
+| `packages/coding-agent/src/humain` | HUMAIN public defaults, theme startup, provider registration, DeployNow descriptor interpretation, unsupported SSO, and exact legacy-tier cleanup. |
+| `packages/agent` | Model-neutral turn loop, message state, tool orchestration, harness contracts. |
+| `packages/ai` | Provider metadata, auth helpers, request transports, Bedrock endpoint/region/credential behavior, OpenAI/Anthropic APIs. |
+| `packages/tui` | Interactive rendering, input, status, selectors, layout, and theme application. |
+
+The main product-specific exception is startup injection: `main.ts` directly imports the HUMAIN extension factory
+so HUMAIN behavior is always bundled into this distribution. That is an allowed public-distribution boundary,
+but the implementation should still keep product policy out of `packages/agent`, `packages/ai`, and `packages/tui`.
+
+## Flow 1: Startup And Cwd Resolution
+
+Startup begins in the CLI entrypoint, then `main()` owns process setup:
+
+```text
+cli.ts
+  -> main(args)
+    -> parse args
+    -> resolveStartupCwd()
+    -> process.chdir(cwd)
+    -> inject HUMAIN extension factories and default packages
+    -> bootstrap settings and package/config commands
+    -> resolve session manager and effective session cwd
+    -> create AgentSessionRuntime
+    -> dispatch interactive, print, JSON, or RPC mode
+```
+
+The cwd precedence is:
+
+1. `--cwd`
+2. `HUMAIN_TERMINAL_DEFAULT_CWD`
+3. `HUMAIN_TERMINAL_FORGE_CWD`
+4. the process cwd
+
+`resolveStartupCwd()` validates that the selected path exists and is a directory before `main()` changes the
+process cwd. Package and config commands run after this resolution, so package/resource behavior observes the
+startup cwd rather than the shell cwd.
+
+Session selection can still change the final runtime cwd. Resume, import, fork, and session paths go through
+`SessionManager`; the runtime factory then recreates cwd-bound services for `sessionManager.getCwd()`. That
+keeps settings, project trust, resources, tools, and provider registrations aligned with the effective session
+cwd.
+
+Key source handles:
+
+- [`src/main.ts`](../src/main.ts#L492) - `resolveStartupCwd()` precedence and validation.
+- [`src/main.ts`](../src/main.ts#L574) - startup cwd application and HUMAIN extension injection.
+- [`src/main.ts`](../src/main.ts#L685) - final runtime cwd is resolved after session lookup.
+- [`src/core/agent-session-runtime.ts`](../src/core/agent-session-runtime.ts#L406) - runtime creation from the resolved session target.
+- [`test/main-startup-cwd.test.ts`](../test/main-startup-cwd.test.ts#L17) - startup cwd regression coverage.
+
+## Flow 2: Settings, Trust, And Resources
+
+Resource loading has three important boundaries:
+
+1. Settings are created for a cwd and agent dir.
+2. Project resources are trust-gated.
+3. Extensions can register providers before the model registry is fully bound.
+
+The service factory creates the core runtime services:
+
+```text
+createAgentSessionServices()
+  -> AuthStorage
+  -> SettingsManager
+  -> ModelRegistry
+  -> DefaultResourceLoader
+  -> resourceLoader.reload()
+  -> flush pending extension provider registrations into ModelRegistry
+```
+
+`DefaultResourceLoader` receives the inline HUMAIN extension factories and default package sources from
+`main.ts`. It then resolves package resources, extension paths, skill paths, prompt templates, themes, context
+files, and system prompt files. Context files use `AGENTS.md` and `CLAUDE.md`; project `.humain-terminal`
+resources require project trust.
+
+Provider registration is intentionally two-phase. During extension load, `pi.registerProvider()` queues
+registrations on the shared extension runtime. Once `createAgentSessionServices()` has a `ModelRegistry`, it
+flushes those queued registrations. After `AgentSession` binds the runner, later provider registrations take
+effect immediately and refresh the current model if needed.
+
+Key source handles:
+
+- [`src/core/agent-session-services.ts`](../src/core/agent-session-services.ts#L137) - cwd-bound service creation.
+- [`src/core/resource-loader.ts`](../src/core/resource-loader.ts#L215) - resource loader inputs.
+- [`src/core/resource-loader.ts`](../src/core/resource-loader.ts#L494) - package/user/project extension loading.
+- [`src/core/resource-loader.ts`](../src/core/resource-loader.ts#L465) - context file loading.
+- [`src/core/extensions/loader.ts`](../src/core/extensions/loader.ts#L213) - queued provider registrations before binding.
+- [`src/core/extensions/runner.ts`](../src/core/extensions/runner.ts#L353) - queued registrations flushed on bind.
+
+## Flow 3: HUMAIN Extension And Provider Registration
+
+HUMAIN Code is implemented as a bundled inline extension, not as a fork of the agent runtime:
+
+```text
+getHumainBundledExtensionFactories(env)
+  -> createHumainProviderExtensionFactory(env)
+    -> register HUMAIN local provider if configured
+    -> register explicit non-SSO HUMAIN Code provider if configured
+    -> register DeployNow binding providers if descriptors are present
+    -> always register unsupported HUMAIN SSO with no models or base URL
+    -> on session_start set the HUMAIN theme at startup
+    -> remove only exact untouched legacy generated tier files
+```
+
+The extension owns these product concepts:
+
+- `HUMAIN_TERMINAL_HC_*` and `HUMAIN_TERMINAL_HUMAIN_CODE_*`
+- DeployNow descriptor sentinels such as `deploynow-proxy` and legacy `deploynow-broker`
+- `FORGE_RUNTIME_MODEL_PROVIDER` and `FORGE_RUNTIME_MODEL_ID`
+- the always-visible `HUMAIN SSO` login entry, whose credential operations reject with
+  `HUMAIN SSO is not supported yet.`
+- conservative cleanup of the exact historical generated mapping at
+  `~/.pi/workflows/model-tiers.json` and `~/.humain-terminal/workflows/model-tiers.json`
+
+The extension no longer registers `/hc` or `/humaincode`, creates or persists HUMAIN model profiles, injects
+Forge prompt text, writes workflow tier configuration, or sets `HUMAIN Code` / `Forge ready` footer status.
+Legacy OIDC configuration does not enable login, token exchange, credentials, models, or a model API endpoint.
+The extension does not detect Forge from directory names or repository shape. Explicit Forge startup cwd support
+is owned by the `main.ts` precedence described in Flow 1.
+
+Key source handles:
+
+- [`src/humain/index.ts`](../src/humain/index.ts) - provider registration, theme startup,
+  unsupported SSO, and legacy generated-tier cleanup.
+- [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) - retained providers, removed
+  routing/status behavior, theme startup, and no tier generation.
+- [`test/legacy-workflow-tiers.test.ts`](../test/legacy-workflow-tiers.test.ts) - exact legacy-tier cleanup and
+  customized-file preservation.
+- [`test/humain-sso.test.ts`](../test/humain-sso.test.ts) - always-visible unsupported SSO behavior.
+
+## Flow 4: DeployNow Runtime Model Binding
+
+DeployNow binding descriptors are interpreted in `src/humain`, then converted into normal provider
+registrations. Real provider secrets are not supposed to live in HUMAIN Terminal; loopback URLs and placeholder
+credentials describe a supervisor-owned route.
+
+```text
+DeployNow env descriptor
+  -> hasDeployNow*BindingConfig()
+  -> getDeployNow*ModelId()
+  -> pi.registerProvider(provider, config)
+  -> ModelRegistry.registerProvider()
+  -> model availability and request auth
+  -> AgentSession streamFn
+  -> packages/ai provider transport
+```
+
+Current descriptor shapes:
+
+| Provider selected by Forge | Required descriptor shape |
+| --- | --- |
+| Bedrock | `ANTHROPIC_BEDROCK_BASE_URL`, sentinel `AWS_ACCESS_KEY_ID`, sentinel `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, and model from `FORGE_RUNTIME_MODEL_ID` or `BEDROCK_MODEL_ID`. |
+| OpenAI | `OPENAI_BASE_URL`, sentinel `OPENAI_API_KEY`, and model from `FORGE_RUNTIME_MODEL_ID` or `OPENAI_MODEL_ID`. |
+| Anthropic | `ANTHROPIC_BASE_URL`, sentinel `ANTHROPIC_API_KEY`, and model from `FORGE_RUNTIME_MODEL_ID` or `ANTHROPIC_MODEL_ID`. |
+
+If `FORGE_RUNTIME_MODEL_PROVIDER` is present, selection is fail-closed. For example, if Forge selects OpenAI but
+only a Bedrock descriptor is complete, the HUMAIN extension does not silently target Bedrock.
+
+For Bedrock, the extension passes provider-scoped env values through `ProviderConfig.env`. The model registry
+returns those values with request auth, and the SDK stream function merges them into `streamSimple()` options.
+`packages/ai` then resolves AWS region, credentials, endpoint behavior, bearer token mode, and Bedrock-specific
+payload details.
+
+Key source handles:
+
+- [`src/humain/index.ts`](../src/humain/index.ts) - DeployNow sentinels, fail-closed model target selection,
+  request env, and Bedrock/OpenAI/Anthropic provider registrations.
+- [`src/core/model-registry.ts`](../src/core/model-registry.ts#L716) - provider request config storage.
+- [`src/core/model-registry.ts`](../src/core/model-registry.ts#L749) - request auth, headers, and env resolution.
+- [`src/core/sdk.ts`](../src/core/sdk.ts#L302) - auth/env/header merge into `streamSimple()`.
+- [`../ai/src/api/bedrock-converse-stream.ts`](../../ai/src/api/bedrock-converse-stream.ts#L132) - Bedrock endpoint and region handling.
+- [`../ai/src/api/bedrock-converse-stream.ts`](../../ai/src/api/bedrock-converse-stream.ts#L969) - AWS credential resolution from provider env.
+- [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) - DeployNow
+  Bedrock/OpenAI/Anthropic binding coverage.
+- [`test/model-registry.test.ts`](../test/model-registry.test.ts#L1252) - provider-scoped request env coverage.
+
+## Flow 5: Non-SSO HUMAIN Code
+
+The explicit non-SSO HUMAIN Code provider path is independent of the unsupported HUMAIN SSO login entry. It
+uses endpoint and API key environment variables:
+
+```text
+HUMAIN_TERMINAL_HC_BASE_URL
+HUMAIN_TERMINAL_HC_API_KEY
+HUMAIN_TERMINAL_HC_MODELS
+```
+
+The long aliases are also supported:
+
+```text
+HUMAIN_TERMINAL_HUMAIN_CODE_BASE_URL
+HUMAIN_TERMINAL_HUMAIN_CODE_API_KEY
+HUMAIN_TERMINAL_HUMAIN_CODE_MODELS
+```
+
+When configured, this registers provider `humain-code` using the OpenAI chat-completions-compatible transport.
+Its models enter the normal model registry and can be selected through `/model`. DeployNow descriptors register
+their own normal providers; neither path creates or changes a HUMAIN model profile.
+
+Key source handles:
+
+- [`src/humain/index.ts`](../src/humain/index.ts) - short and long HUMAIN Code env aliases and provider
+  registration.
+- [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) - explicit non-SSO HUMAIN
+  Code coverage.
+
+## Flow 6: Normal Model And Workflow Selection
+
+HUMAIN Terminal uses the normal coding-agent model flow:
+
+```text
+user runs /login for a supported provider
+  -> AuthStorage persists supported provider credentials
+user runs /model
+  -> ModelRegistry lists available registered models
+  -> AgentSession.setModel() applies the auth gate
+  -> normal default-model settings and session restoration persist selection
+```
+
+Dynamic workflows retain ownership of their model-selection behavior. HUMAIN Terminal does not create tier files,
+model profiles, or a second routing layer. `/hc` and
+`/humaincode` are not registered, and no Forge context is injected into prompts. The `hc` executable alias still
+starts the same CLI, while `HUMAIN_TERMINAL_FORGE_CWD` remains a startup cwd fallback.
+
+Key source handles:
+
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts) - model auth gate and session model switching.
+- [`src/modes/interactive/interactive-mode.ts`](../src/modes/interactive/interactive-mode.ts) - `/login` and
+  `/model` interactive flows.
+- [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) - absence of HUMAIN routing,
+  profiles, prompt injection, generated tiers, and product footer status.
+
+## Flow 7: Prompt To Provider Request
+
+All modes converge on `AgentSession`:
+
+```text
+interactive / print / JSON / RPC
+  -> AgentSession.prompt()
+    -> extension command check
+    -> extension input handlers
+    -> skill command expansion
+    -> prompt template expansion
+    -> streaming queue handling
+    -> model/auth validation
+    -> before_agent_start extension hook
+    -> Agent prompt/run loop
+    -> streamFn(model, context, options)
+    -> ModelRegistry.getApiKeyAndHeaders(model)
+    -> streamSimple(model, context, request options)
+    -> packages/ai provider implementation
+```
+
+The provider request hook exists after provider selection. `createAgentSession()` passes `onPayload` and
+`onResponse` callbacks into `streamSimple()`, and those call extension `before_provider_request` and
+`after_provider_response` handlers. The DeployNow credential path does not rely on these hooks today; it uses
+provider registration plus request-scoped env. Payload hooks are still useful for payload-level mutation and
+inspection.
+
+Key source handles:
+
+- [`src/core/sdk.ts`](../src/core/sdk.ts#L302) - Agent construction and stream function.
+- [`src/core/sdk.ts`](../src/core/sdk.ts#L340) - provider payload and response hooks.
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts#L1076) - prompt preflight path.
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts#L1144) - model/auth validation before prompt execution.
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts#L1183) - `before_agent_start` hook.
+- [`src/core/extensions/runner.ts`](../src/core/extensions/runner.ts#L976) - provider payload hook dispatch.
+- [`src/modes/rpc/rpc-mode.ts`](../src/modes/rpc/rpc-mode.ts#L473) - RPC model selection through `session.setModel()`.
+- [`src/modes/interactive/interactive-mode.ts`](../src/modes/interactive/interactive-mode.ts#L4239) - interactive model command through `session.setModel()`.
+
+## Flow 8: Tools, Events, And Persistence
+
+Default tool activation happens in session creation. Unless constrained, the active built-in tools start as
+`read`, `bash`, `edit`, and `write`. Extension tools are registered through the extension runtime and then
+wrapped into agent tools with an extension context.
+
+Tool calls move through three layers:
+
+```text
+model emits tool call
+  -> agent validates tool call shape
+  -> AgentSession beforeToolCall hook bridge
+  -> built-in or extension tool executes
+  -> AgentSession afterToolCall hook bridge
+  -> tool result message returns to the model loop
+  -> session manager persists JSONL entries and branch state
+```
+
+The session runtime owns replacement flows such as new session, resume, fork, import, and tree navigation. It
+tears down the current session, creates cwd-bound services again for the target, and rebinds UI/RPC session
+handles. That is why session cwd and resource loading are runtime concepts, not one-time startup facts.
+
+Key source handles:
+
+- [`src/core/sdk.ts`](../src/core/sdk.ts#L245) - default active tools.
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts#L424) - tool call hook bridge.
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts#L2176) - extension binding to session actions.
+- [`src/core/agent-session.ts`](../src/core/agent-session.ts#L2397) - tool registry refresh.
+- [`src/core/agent-session-runtime.ts`](../src/core/agent-session-runtime.ts#L260) - fork replacement flow.
+- [`src/core/agent-session-runtime.ts`](../src/core/agent-session-runtime.ts#L353) - import replacement flow.
+
+## What Is Not Ideal
+
+These are current pressure points, not all immediate bugs:
+
+| Pressure point | Why it matters | Current mitigation |
+| --- | --- | --- |
+| The HUMAIN extension owns provider registration, theme startup, unsupported SSO, and legacy cleanup. | The extension remains a product integration point, so unrelated changes can still churn one file. | Keep generic pieces out of it; split only when a sub-concern grows enough to need its own module. |
+| Startup imports HUMAIN extension factories directly. | This is a product boundary exception inside CLI bootstrap. | Treat it as distribution wiring only; do not use `main.ts` for Forge policy. |
+| Forge cwd selection is explicit. | Incorrect `--cwd` or environment configuration can still select the wrong directory. | Keep the documented precedence and path validation covered by startup tests. |
+| DeployNow descriptors are env-shaped but not real secrets. | It is easy to mistake placeholder credentials for provider credentials. | Docs and tests call them descriptors, and real secrets remain behind supervisor/auth-broker systems. |
+| Provider availability is API-key-shaped in several paths. | Header-only or ambient-auth providers need careful alignment between `hasConfiguredAuth()`, status, and request-time behavior. | Bedrock and DeployNow registrations provide an apiKey-shaped descriptor; model-registry tests cover request env. |
+| File-backed provider config and dynamic extension provider config overlap but are not identical. | Contributors may assume every dynamic `ProviderConfig` field maps directly to JSON config, or the reverse. | Keep dynamic behavior documented in custom-provider docs and model registry tests. |
+| Provider payload hooks exist below model selection. | They can mutate payloads, but they are not a replacement for provider registration or model selection. | Use provider registration for auth/env/model access; use hooks for payload mutation/inspection. |
+| Internal wording still references `pi` in generic system prompt and package internals. | Branding is public-facing HUMAIN, but upstream-compatible internals remain. | The architecture contract explicitly preserves upstream-compatible internals unless a package-scope migration is deliberate. |
+| Operator docs and architecture docs can drift into each other. | `humain-terminal.md` needs runnable env guidance, while architecture pages need ownership rules and current flow. | Keep operator examples in `humain-terminal.md`; link to architecture and this walkthrough for design reasoning. |
+
+## Delta Against The Architecture Contract
+
+Current alignment:
+
+- HUMAIN/Forge behavior is mostly concentrated in `packages/coding-agent/src/humain`.
+- DeployNow model bindings enter as normal provider registrations.
+- Request auth, headers, and provider-scoped env flow through `ModelRegistry` and `streamSimple()`.
+- Bedrock region, endpoint, credentials, and payload behavior remain in `packages/ai`.
+- `/login`, `/model`, default-model settings, and session restoration own normal model selection.
+- Dynamic workflows retain their own model-selection behavior without HUMAIN-generated routing.
+- The HUMAIN extension does not register routing commands, profiles, prompt injection, generated tiers, or product
+  footer status.
+- HUMAIN SSO stays visible in `/login` but has no models or base URL and rejects all credential operations as
+  unsupported.
+
+Current deltas to watch:
+
+- The HUMAIN extension is a growing composition point and may need internal subdivision if more Forge behavior is
+  added.
+- Some public docs need to link instead of duplicating architecture doctrine.
+- Request hooks are available, but new Forge auth/provider work should not use them to bypass provider/model
+  registration.
+- Do not reintroduce structural Forge detection; keep startup cwd explicit and tested.
+
+## Verification Map
+
+| Behavior | Current proof surface |
+| --- | --- |
+| Startup cwd fallback and `--cwd` handling | [`test/main-startup-cwd.test.ts`](../test/main-startup-cwd.test.ts) |
+| Removed routing commands, generated tiers, and product status | [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) |
+| Exact legacy-tier cleanup and customized-file preservation | [`test/legacy-workflow-tiers.test.ts`](../test/legacy-workflow-tiers.test.ts) |
+| Always-visible unsupported HUMAIN SSO | [`test/humain-sso.test.ts`](../test/humain-sso.test.ts) |
+| Non-SSO HUMAIN Code provider config | [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) |
+| DeployNow Bedrock/OpenAI/Anthropic binding descriptors | [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) |
+| Explicit provider fail-closed behavior | [`test/humain-forge-extension.test.ts`](../test/humain-forge-extension.test.ts) |
+| Provider-scoped request env | [`test/model-registry.test.ts`](../test/model-registry.test.ts#L1252) |
+| Model selection auth gate | [`src/core/agent-session.ts`](../src/core/agent-session.ts#L1537) and mode-specific calls to `session.setModel()`. |
+
+## Guidance For Future Changes
+
+When changing this architecture, answer these questions before editing:
+
+1. Which layer owns the behavior?
+2. Is this a descriptor, a provider registration, model selection, request auth, a payload mutation, a tool, or UI state?
+3. Does this need to happen at startup, resource load, session runtime creation, command handling, or request time?
+4. Which existing seam carries it without bypassing `ModelRegistry`, `AgentSession`, or provider transport?
+5. Which focused test proves it without real provider secrets?
+
+If the answer is "Forge needs a model," start with provider registration and normal `/model` selection. If the answer is
+"Forge needs to mutate a provider payload," use the provider payload hook. If the answer is "Forge needs
+credential custody," that belongs outside this repo in Forge/DeployNow supervisor and auth-broker systems.

package/docs/humain-terminal.md

@@ -0,0 +1,102 @@
+# HUMAIN Terminal
+
+HUMAIN Terminal is the branded distribution of the coding agent. The primary command is `humain-terminal`; `humain` and `hc` are executable aliases for the same CLI.
+
+## Config
+
+HUMAIN Terminal stores user settings under `~/.humain-terminal/agent` by default. The shell-safe environment prefix is `HUMAIN_TERMINAL`.
+
+Useful distribution-specific environment variables:
+
+- `HUMAIN_TERMINAL_CODING_AGENT_DIR` - override the agent config directory.
+- `HUMAIN_TERMINAL_CODING_AGENT_SESSION_DIR` - override session storage.
+- `HUMAIN_TERMINAL_DEFAULT_CWD` - default project directory when `--cwd` is not provided.
+- `HUMAIN_TERMINAL_PACKAGE_DIR` - override bundled package asset lookup.
+- `HUMAIN_TERMINAL_OFFLINE` - disable startup network operations.
+- `HUMAIN_TERMINAL_SKIP_VERSION_CHECK` - disable startup version checks.
+- `HUMAIN_TERMINAL_VERSION_CHECK_URL` - override the latest-version endpoint.
+- `HUMAIN_TERMINAL_TELEMETRY` - override install/update telemetry.
+- `HUMAIN_TERMINAL_INSTALL_TELEMETRY_URL` - override the install/update telemetry endpoint.
+- `HUMAIN_TERMINAL_CHANGELOG_URL` - override the release changelog URL.
+- `HUMAIN_TERMINAL_BINARY_RELEASE_URL` - override the binary self-update fallback URL.
+- `HUMAIN_TERMINAL_SHARE_VIEWER_URL` - override the `/share` viewer base URL.
+
+`--cwd <dir>` is resolved before package/config commands, migrations, settings, session lookup, resource loading, and runtime creation.
+
+```bash
+humain-terminal --cwd /Users/akarim/Documents/Work/forge
+```
+
+## Built-Ins
+
+HUMAIN Terminal includes `humain-dark` and `humain-light` themes and uses `humain-dark` on first startup unless the user changes settings.
+
+The runtime loads default package sources for dynamic workflows, web access, MCP integration, and queue/steering without writing them to settings.
+
+Configured user or project packages with the same npm package identity override the default source.
+
+## Local Models
+
+Set `HUMAIN_TERMINAL_LOCAL_BASE_URL` to an OpenAI-compatible `/v1` endpoint. Models come from `HUMAIN_TERMINAL_LOCAL_MODELS` when set, otherwise HUMAIN Terminal performs a bounded `/v1/models` discovery request.
+
+```bash
+HUMAIN_TERMINAL_LOCAL_BASE_URL=http://127.0.0.1:8000/v1 \
+HUMAIN_TERMINAL_LOCAL_MODELS=qwen3-coder-480b-a35b-instruct \
+humain-terminal
+```
+
+Optional:
+
+- `HUMAIN_TERMINAL_LOCAL_API_KEY` - API key for the local endpoint.
+- `HUMAIN_TERMINAL_LOCAL_MODELS_DISCOVERY_TIMEOUT_MS` - model discovery timeout, default `750`.
+
+## HUMAIN Code Models
+
+Inside DeployNow/Forge sandboxes, HUMAIN Terminal reads the runtime model binding descriptor shape that DeployNow exposes to workloads. These values identify a loopback binding URL and placeholder credentials, not real provider secrets:
+
+For layer ownership, review rules, and do/don't guidance, see [HUMAIN Code / Forge Architecture](humain-code-forge-architecture.md). For the current startup, resource loading, provider binding, model-selection, and request-auth data flow, see [HUMAIN Code / Forge Flow Walkthrough](humain-code-forge-flow-walkthrough.md).
+
+```bash
+ANTHROPIC_BEDROCK_BASE_URL=http://127.0.0.1:7777/bindings/inference/bedrock
+AWS_ACCESS_KEY_ID=deploynow-proxy
+AWS_SECRET_ACCESS_KEY=deploynow-proxy
+AWS_REGION=eu-west-2
+BEDROCK_MODEL_ID=global.anthropic.claude-haiku-4-5-20251001-v1:0
+```
+
+When that shape is present, HUMAIN Terminal registers the selected `amazon-bedrock` runtime model against the local DeployNow binding proxy. Select the registered model through `/model`. Existing Forge adapter handoffs that still use `deploynow-broker` placeholder AWS credentials are accepted for compatibility, but new bindings should use `deploynow-proxy`. The real provider credentials stay behind the supervisor/auth-broker path.
+
+OpenAI and Anthropic binding descriptors are recognized the same way when DeployNow provides `OPENAI_BASE_URL`/`OPENAI_API_KEY=deploynow-proxy` or `ANTHROPIC_BASE_URL`/`ANTHROPIC_API_KEY=deploynow-proxy`. When `FORGE_RUNTIME_MODEL_PROVIDER` and `FORGE_RUNTIME_MODEL_ID` identify one of those providers, HUMAIN Terminal registers that runtime model through the loopback binding. OpenAI bindings use the chat-completions-compatible API path.
+
+For non-DeployNow environments, set both `HUMAIN_TERMINAL_HC_BASE_URL` and `HUMAIN_TERMINAL_HC_API_KEY` to register an OpenAI-compatible `humain-code` provider for Forge. Models come from `HUMAIN_TERMINAL_HC_MODELS` when set; registered models are selected through the normal `/model` command.
+
+```bash
+HUMAIN_TERMINAL_FORGE_CWD=/Users/akarim/Documents/Work/forge \
+HUMAIN_TERMINAL_HC_BASE_URL=https://inference.example/v1 \
+HUMAIN_TERMINAL_HC_API_KEY=... \
+humain-terminal
+```
+
+The long environment variable aliases `HUMAIN_TERMINAL_HUMAIN_CODE_BASE_URL`, `HUMAIN_TERMINAL_HUMAIN_CODE_API_KEY`, and `HUMAIN_TERMINAL_HUMAIN_CODE_MODELS` are also supported.
+
+## HUMAIN SSO
+
+`HUMAIN SSO` is always visible in `/login`, but it is not a functional authentication or model provider. Selecting it fails with:
+
+```text
+HUMAIN SSO is not supported yet.
+```
+
+The provider has no models or model API base URL. Legacy OIDC issuer, client, endpoint, redirect, scope, model API, and token environment variables do not enable SSO, open a browser, request a code, or persist credentials.
+
+## Model Selection And Workflows
+
+Use `/login` to authenticate with a supported provider and `/model` to select one of its available models. Normal session restoration and default-model settings determine the active model on later starts.
+
+The former `/hc` and `/humaincode` slash commands are not registered. HUMAIN Terminal does not create HUMAIN model profiles, inject Forge prompt text, or set `HUMAIN Code` or `Forge ready` footer statuses. The `hc` executable alias is unaffected and still starts HUMAIN Terminal.
+
+Set `HUMAIN_TERMINAL_FORGE_CWD` to make Forge the startup working directory when `--cwd` and `HUMAIN_TERMINAL_DEFAULT_CWD` are not set.
+
+HUMAIN Terminal does not generate dynamic-workflows `small`, `medium`, or `big` tier files. Workflow model choice remains owned by the dynamic-workflows package; HUMAIN Terminal does not add a second model-routing layer.
+
+At startup, HUMAIN Terminal checks both `~/.pi/workflows/model-tiers.json` and `~/.humain-terminal/workflows/model-tiers.json`. It removes a file only when it contains the exact untouched legacy generated mapping; customized, extended, or malformed files are preserved unchanged.

package/docs/index.md

@@ -0,0 +1,82 @@
+# HUMAIN Terminal Documentation
+
+HUMAIN Terminal is a model-flexible terminal coding harness for HUMAIN engineering and client workflows. It stays small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and packages.
+
+## Quick start
+
+Install HUMAIN Terminal with npm:
+
+```bash
+npm install -g --ignore-scripts @humain/terminal
+```
+
+`--ignore-scripts` disables dependency lifecycle scripts during install. HUMAIN Terminal does not require install scripts for normal npm installs.
+
+To uninstall HUMAIN Terminal itself, use the package manager that installed it:
+
+```bash
+npm uninstall -g @humain/terminal
+```
+
+For pnpm, Yarn, or Bun installs, use the matching global remove command with the HUMAIN Terminal package name.
+
+Then run it in a project directory:
+
+```bash
+humain-terminal
+```
+
+Authenticate with `/login` for a supported subscription provider, or set an API key such as `ANTHROPIC_API_KEY` before starting HUMAIN Terminal. Use `/model` to select the active model.
+
+For the full first-run flow, see [Quickstart](quickstart.md).
+
+## Start here
+
+- [Quickstart](quickstart.md) - install, authenticate, and run a first session.
+- [Using HUMAIN Terminal](usage.md) - interactive mode, slash commands, context files, and CLI reference.
+- [HUMAIN Terminal](humain-terminal.md) - branded command names, config, themes, normal model selection, unsupported HUMAIN SSO, local models, and Forge startup.
+- [HUMAIN Code / Forge Architecture](humain-code-forge-architecture.md) - architecture principles, layer ownership, and do/don't guidance for HUMAIN Code and Forge changes.
+- [HUMAIN Code / Forge Flow Walkthrough](humain-code-forge-flow-walkthrough.md) - current startup, resource, provider, workflow model-selection ownership, and request-auth data flow with known pressure points.
+- [HUMAIN Code / Forge Component Scorecard](humain-code-forge-component-scorecard.md) - scored component audit with required fixes, mitigations, and architecture-ratchet gaps.
+- [Providers](providers.md) - subscription and API-key setup for built-in providers.
+- [llama.cpp](llama-cpp.md) - run a local router and manage models with `/llama`.
+- [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting.
+- [Containerization](containerization.md) - sandbox HUMAIN Terminal with Gondolin, Docker, or OpenShell.
+- [Settings](settings.md) - global and project settings.
+- [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
+- [Sessions](sessions.md) - session management, branching, and tree navigation.
+- [Compaction](compaction.md) - context compaction and branch summarization.
+
+## Customization
+
+- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
+- [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
+- [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
+- [Themes](themes.md) - built-in and custom terminal themes.
+- [Packages](packages.md) - bundle and share extensions, skills, prompts, and themes.
+- [Custom models](models.md) - add model entries for supported provider APIs.
+- [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
+
+## Programmatic usage
+
+- [SDK](sdk.md) - embed HUMAIN Terminal in Node.js applications.
+- [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
+- [JSON event stream mode](json.md) - print mode with structured events.
+- [TUI components](tui.md) - build custom terminal UI for extensions.
+
+## Reference
+
+- [Environment variables](environment-variables.md) - HUMAIN Terminal process configuration and session metadata available to bash tools.
+- [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
+
+## Platform setup
+
+- [Windows](windows.md)
+- [Termux on Android](termux.md)
+- [tmux](tmux.md)
+- [Terminal setup](terminal-setup.md)
+- [Shell aliases](shell-aliases.md)
+
+## Development
+
+- [Development](development.md) - local setup, project structure, and debugging.