@humain/terminal 0.0.1

package/docs/humain-code-forge-architecture.md

@@ -0,0 +1,217 @@
+# HUMAIN Code / Forge Architecture
+
+This is the canonical architecture contract for HUMAIN Code and Forge-specific work in HUMAIN Terminal.
+Read it before changing Forge startup behavior, DeployNow model bindings, bundled HUMAIN providers, workflow
+model selection, provider/auth registration, Bedrock transport, or HUMAIN branding/config paths.
+
+For the descriptive current-state data flow and known pressure points, read the companion
+[HUMAIN Code / Forge Flow Walkthrough](humain-code-forge-flow-walkthrough.md).
+For the current implementation audit, read the
+[HUMAIN Code / Forge Component Scorecard](humain-code-forge-component-scorecard.md).
+
+The operating rule is simple: keep HUMAIN and Forge behavior first-class without turning it into a fork of the
+agent runtime or leaking product-specific concerns into generic provider, agent, or TUI layers.
+
+This page is normative. If another README, PRD, roadmap, or implementation note conflicts with this page, treat
+this page as the source of truth for the current architecture. If the architecture intentionally changes, update
+this page in the same change as the code and tests that establish the new boundary.
+
+## North Star
+
+HUMAIN Terminal should be a drop-in terminal coding agent for Forge and HUMAIN Code workflows while still
+remaining an upstream-compatible, model-flexible coding-agent distribution. The product layer should feel native
+to HUMAIN users, but the underlying runtime should stay generic enough to keep accepting upstream fixes,
+provider improvements, extension changes, and TUI improvements without repeated product-specific conflict.
+
+That means:
+
+- HUMAIN and Forge behavior should be obvious and well supported.
+- Generic runtime packages should stay reusable and provider/product-neutral.
+- Provider and credential behavior should be modeled through normal registry and request-auth contracts.
+- Docs and tests should make the boundary visible enough that future agents do not have to rediscover it.
+
+## Core Principles
+
+1. **Forge is first-class, but configuration-driven.** Support Forge startup through explicit `--cwd`, settings,
+   and `HUMAIN_TERMINAL_FORGE_CWD` precedence. Do not infer Forge identity structurally or hardcode a developer
+   machine path as runtime behavior.
+2. **HUMAIN Code is a provider-registration layer.** Add HUMAIN-specific providers, theme setup, default
+   packages, and narrowly scoped legacy cleanup through the bundled HUMAIN extension and normal resource seams.
+   Forge startup cwd stays in `main.ts`; model selection stays in the normal session flow.
+3. **Runtime model bindings are normal provider registrations.** DeployNow bindings should enter through the
+   same provider/model registry and request-auth machinery as other providers.
+4. **DeployNow credentials are descriptors, not secrets.** Loopback binding URLs and placeholder credentials
+   describe a supervisor-owned route. Real provider credentials stay behind the supervisor/auth-broker path.
+5. **Provider choice is explicit and fail-closed within DeployNow binding resolution.** If
+   `FORGE_RUNTIME_MODEL_PROVIDER` selects a provider, an incomplete binding for that provider must not silently
+   fall through to another DeployNow binding. When no selected DeployNow binding can be registered, the existing
+   non-DeployNow registry and active-session model path may still apply.
+6. **Generic transport behavior belongs in `packages/ai`.** Bedrock endpoint resolution, proxy handling, HTTP
+   handler selection, model metadata, and provider stream behavior are not HUMAIN or Forge concerns.
+7. **Availability, status, and request auth must agree.** If a provider config option affects request-time
+   auth, keep `hasConfiguredAuth`, auth status, and request auth resolution consistent.
+8. **Docs and tests are contract surfaces.** Changes to binding shapes, sentinels, provider precedence, model
+   selection, or transport behavior must update the docs and focused regression tests that describe them.
+9. **Preserve upstream-compatible internals.** Keep internal package names and import boundaries close to the
+   upstream project unless the package scope is deliberately migrated. Put HUMAIN branding at public boundaries.
+10. **Do not imply sandboxing that does not exist.** Project trust, provider registration, and model selection
+    are not process, filesystem, network, or credential isolation.
+11. **HUMAIN SSO is visible but unsupported.** Keep `HUMAIN SSO` in `/login`, with no models or model API base
+    URL. Login and refresh operations must reject with `HUMAIN SSO is not supported yet.` Legacy OIDC
+    configuration must not enable it.
+12. **Drop-in replacement means behavioral compatibility, not internal mimicry.** Preserve the CLI/package
+    surfaces, config paths, working-directory behavior, provider/model selection, and tool/session behavior Forge
+    needs.
+    Do not copy Claude Code internals or add compatibility shims outside the owning layer just to match names.
+
+## Layer Ownership
+
+| Layer | Owns | Must Not Own |
+| --- | --- | --- |
+| `packages/ai` | Provider APIs, model metadata, streaming implementations, Bedrock endpoint/proxy/HTTP behavior, provider-neutral auth inputs. | Forge prompt injection, DeployNow sentinel policy, HUMAIN branding. |
+| `packages/agent` | Model-agnostic agent loop, message state, tool call orchestration, harness contracts. | Provider-specific selection, HUMAIN/Forge env interpretation, TUI rendering policy. |
+| `packages/tui` | Terminal rendering, input, focus, layout primitives, theme application primitives. | Agent workflow policy, provider auth, Forge product status. |
+| `packages/coding-agent/src/main.ts` | CLI bootstrap, startup cwd resolution, app mode dispatch, runtime factory construction, distribution wiring for bundled HUMAIN extension factories. | Forge policy, provider selection policy, DeployNow descriptor parsing beyond passing env into the runtime. |
+| `packages/coding-agent/src/core` | Sessions, settings, auth storage, model registry, resource loading, tools, extension runtime. | Product-specific Forge workflow copy or DeployNow env names. |
+| `packages/coding-agent/src/modes` | Interactive, print, and RPC mode I/O behavior. | Provider detection, model binding interpretation, package-specific architecture rules. |
+| `packages/coding-agent/src/humain` | HUMAIN branding hooks, HUMAIN themes/logo, legacy generated-tier cleanup, DeployNow binding descriptor interpretation, bundled HUMAIN provider registration, and the always-visible unsupported HUMAIN SSO entry. | Startup cwd resolution, generic auth resolution, generic provider transport behavior, workflow model policy, low-level TUI mechanics, real provider secret custody. |
+| `packages/coding-agent/docs` | Durable user and engineering contract for HUMAIN Terminal behavior. | Stale implementation plans or speculative roadmap as current architecture truth. |
+| `docs/superpowers/specs` | Historical product specs and implementation plans. | Canonical current architecture rules after implementation has landed. |
+
+## HUMAIN Code And Forge Boundaries
+
+HUMAIN Code and Forge integration should stay in the bundled HUMAIN extension unless the change is plainly
+generic:
+
+- HUMAIN theme startup, provider registration, and exact legacy generated-tier cleanup belong in
+  `packages/coding-agent/src/humain`; explicit Forge startup cwd resolution belongs in `main.ts`.
+- DeployNow binding descriptor detection belongs in the HUMAIN extension.
+- Dynamic provider registration and provider-scoped request env belong in the model registry and extension API.
+- Normal authentication and model selection belong to `/login`, `/model`, session restoration, and default-model
+  settings.
+- Dynamic workflows own workflow model selection; HUMAIN Terminal does not generate tiers or impose profile
+  routing on the package.
+- Bedrock HTTP/1, proxy bypass, AWS credential resolution, and endpoint handling belong in `packages/ai`.
+- Real Forge app provisioning, provider-key storage, auth-broker registration, and DeployNow supervisor behavior
+  belong to Forge/DeployNow systems, not this repo. HUMAIN Terminal consumes their exported descriptors.
+
+The bundled extension must not reintroduce `/hc` or `/humaincode` routing, HUMAIN model profiles, Forge prompt
+injection, generated workflow tiers, or `HUMAIN Code` / `Forge ready` footer statuses. The `hc` executable alias
+and Forge startup cwd fallback are separate public surfaces and remain supported.
+
+When adding a new Forge or HUMAIN Code behavior, prefer this order:
+
+1. Existing settings, package, prompt, skill, extension, or provider-registration seam.
+2. Bundled HUMAIN extension logic.
+3. Generic coding-agent core only if the behavior is provider/product-neutral.
+4. `packages/ai` only if the behavior is a generic provider/API transport issue.
+
+## Decision Order
+
+Use this order before changing code:
+
+1. **Classify the user-visible behavior.** Is this branding, Forge startup, model selection, provider transport,
+   session/tool behavior, TUI presentation, docs, or release/package metadata?
+2. **Pick the owner by layer.** Product behavior starts in `packages/coding-agent/src/humain`; generic provider
+   transport starts in `packages/ai`; generic agent loop changes start in `packages/agent`; rendering starts in
+   `packages/tui`.
+3. **Use an existing seam first.** Prefer settings, extension APIs, provider registration,
+   provider-scoped request env, package resources, or resource loading before adding new global state.
+4. **Keep external custody external.** If the behavior requires real provider credentials, Forge project
+   authorization, DeployNow supervisor state, or auth-broker signing secrets, this repo should consume a
+   descriptor or documented contract rather than become the owner.
+5. **Fail closed on explicit DeployNow choices.** If Forge explicitly selected a DeployNow provider/model, an
+   incomplete selected binding must not target a different DeployNow provider. Either register the selected
+   binding when its descriptor is complete, or leave DeployNow unselected so normal registry/session model
+   selection remains explicit.
+6. **Prove the boundary.** Add or update the smallest focused test and docs page that would fail if the behavior
+   drifted back across layers.
+
+## Change Classification
+
+| If the change is about... | Start in... | Evidence to update |
+| --- | --- | --- |
+| HUMAIN theme, bundled provider registration, unsupported SSO, or exact legacy-tier cleanup | `packages/coding-agent/src/humain` | HUMAIN extension and SSO tests plus operator docs. |
+| DeployNow descriptor parsing or provider registration from Forge env | `packages/coding-agent/src/humain` plus model registry seams | HUMAIN Forge extension tests and flow docs. |
+| Request-scoped auth, provider availability, selected model behavior | `packages/coding-agent/src/core/model-registry*` | Model registry/auth tests and command path tests. |
+| Bedrock endpoint, AWS env, HTTP handler, stream payloads, provider metadata | `packages/ai` | Provider/API tests and generated metadata checks. |
+| CLI cwd, startup resource injection, package/config command cwd behavior | `packages/coding-agent/src/main.ts` | Startup cwd tests and development docs. |
+| Interactive rendering, key handling, theme rendering, terminal layout | `packages/tui` or interactive mode files | TUI/mode tests or screenshot/manual QA where applicable. |
+| Package aliases, npm package content, shrinkwrap, release artifacts | `packages/coding-agent/package.json`, release scripts | Package command tests, shrinkwrap check, release docs. |
+| Architecture, operator instructions, known flow, scorecards | `packages/coding-agent/docs` | Link inspection and docs consistency review. |
+
+## Do / Don't
+
+| Do | Don't |
+| --- | --- |
+| Register local, explicit `humain-code`, and DeployNow models through normal provider APIs. | Reintroduce `/hc` or `/humaincode` routing, model profiles, or Forge prompt injection. |
+| Register DeployNow runtime models as normal providers/models. | Special-case DeployNow models outside the registry or bypass `hasConfiguredAuth`/`setModel`. |
+| Treat `deploynow-proxy`, `deploynow-broker`, and legacy placeholders as descriptors for a loopback route. | Document or store real provider secrets as if they were part of HUMAIN Terminal. |
+| Keep explicit provider selection fail-closed. | Fall back from explicit `FORGE_RUNTIME_MODEL_PROVIDER=openai` to Bedrock just because Bedrock env exists. |
+| Keep HUMAIN SSO visible but unsupported while non-SSO HUMAIN Code and DeployNow remain independent model-access paths. | Let legacy OIDC variables enable login, token exchange, credentials, or `humain-sso` models. |
+| Put generic Bedrock custom-endpoint fixes in `packages/ai`. | Put AWS SDK handler or proxy details in HUMAIN extension policy. |
+| Keep `ProviderConfig` request auth, availability, and status behavior aligned. | Add provider config fields that only work during the final request path. |
+| Prefer existing settings, extension, workflow, and provider seams before adding new globals. | Add another global env flag when an existing resource or provider contract can carry the behavior. |
+| Keep Forge startup cwd explicit and configurable through `--cwd` and documented environment precedence. | Infer Forge identity from directory names or repository shape, or treat a local path such as `/Users/.../forge` as a product rule. |
+| Use explicit descriptors for externally owned routes and secrets. | Copy Forge provider-key storage, auth-broker signing, or DeployNow supervisor behavior into this repo. |
+| Link operator docs to this architecture contract when changing binding behavior. | Let `humain-terminal.md` become a mixed operator manual plus architecture doctrine. |
+| Preserve upstream-compatible internals when branding public behavior. | Rename internal packages, imports, or generated metadata solely to remove upstream naming. |
+| Keep Claude Code replacement behavior at the CLI/tool/session surface. | Chase Claude Code internals or duplicate unrelated Claude-specific assumptions. |
+| Run focused regression tests for the owning layer. | Prove Forge behavior with real provider calls, secrets, or broad e2e tests when a fake provider/unit test covers the contract. |
+| Update changelogs for shipped package behavior. | Treat docs-only product specs as current proof after code has moved on. |
+
+## Anti-Patterns To Stop Early
+
+- Adding HUMAIN, Forge, or DeployNow checks inside `packages/agent`, `packages/ai`, or `packages/tui` when the
+  behavior is product workflow rather than generic transport/rendering.
+- Solving provider availability in one place and request auth in another, leaving status, `/model`, and runtime
+  calls disagreeing.
+- Reintroducing a product-specific routing layer on top of `/login`, `/model`, session restoration, or
+  dynamic-workflows model selection.
+- Treating placeholder API keys or loopback URLs as real secrets.
+- Treating unsupported HUMAIN SSO as a prerequisite for any model access.
+- Making root README guidance diverge from this architecture contract.
+- Adding broad compatibility layers to mimic another coding agent when Forge only needs command, cwd, tool,
+  session, model, or package compatibility.
+- Using real provider credentials, live DeployNow state, or broad e2e tests when a fake provider and focused
+  unit test can prove the contract.
+- Allowing generated/package metadata churn to hide an architecture boundary change.
+
+## Change Review Rubric
+
+Before editing, classify the change with four questions:
+
+1. **Owning layer:** Which layer should own the behavior?
+2. **Side-effect boundary:** What external state can this change touch: files, sessions, settings, auth, network,
+   provider APIs, packages, or UI state?
+3. **Reused contract:** Which existing seam should carry it: settings, registry, extension API, package source,
+   resource loader, workflow configuration, stream options, or provider transport?
+4. **Evidence boundary:** Which test or doc proves the behavior without relying on real provider credentials or
+   unrelated systems?
+
+If the owning layer is unclear, stop and inspect sibling behavior before patching.
+
+## Verification Matrix
+
+| Change Type | Expected Verification |
+| --- | --- |
+| HUMAIN extension providers, unsupported SSO, or legacy cleanup | Focused `packages/coding-agent` tests around `test/humain-*.test.ts`. |
+| Provider registry/auth behavior | Focused model registry/auth-storage tests plus command path tests if UI commands consume it. |
+| Bedrock or other provider transport behavior | Focused `packages/ai` provider/API tests. |
+| Startup cwd or CLI argument behavior | Focused startup/args tests in `packages/coding-agent/test`. |
+| Docs-only architecture or operator changes | Link check by inspection; no code gate required unless a generated docs step exists. |
+| Code changes outside docs | Run root `npm run check` after focused tests. |
+
+## Future-Agent Checklist
+
+- Read this page before touching HUMAIN Code, Forge, DeployNow bindings, provider registration, Bedrock custom
+  endpoint behavior, bundled packages, or workflow model selection.
+- Start with the current live source and tests, not older plans.
+- State the owning layer before making a non-trivial change.
+- Prefer existing extension, settings, workflow, package, resource, registry, or provider seams before inventing a
+  new abstraction.
+- Keep product policy out of generic runtime layers unless the behavior is demonstrably provider/product-neutral.
+- Preserve CLI/package/config compatibility for Forge-facing surfaces.
+- Keep one canonical architecture contract here. Link from other pages instead of duplicating the doctrine.
+- If a change violates one of these rules intentionally, write down the tradeoff in the commit or PR notes and
+  add a regression test for the new boundary.

package/docs/humain-code-forge-component-scorecard.md

@@ -0,0 +1,122 @@
+# HUMAIN Code / Forge Component Scorecard
+
+This scorecard records how the implementation observed on 2026-07-01 aligned with the
+[HUMAIN Code / Forge Architecture](humain-code-forge-architecture.md) contract and the descriptive
+[HUMAIN Code / Forge Flow Walkthrough](humain-code-forge-flow-walkthrough.md).
+
+The audit was produced on 2026-07-01 with an Ultracode multi-agent pass and a local source review. It records
+the implementation as observed on that date, not the current architecture contract.
+
+## Follow-up: 2026-07-15
+
+The HUMAIN routing and SSO simplification supersedes several current-state claims in the original audit below.
+The original scores, evidence, and required fixes remain unchanged as historical audit provenance; this targeted
+follow-up is not a new full scorecard pass, so the **7.8/10** score has not been recalculated.
+
+Current behavior after the follow-up:
+
+- `/hc` and `/humaincode` routing, HUMAIN model profiles, Forge prompt injection, product footer statuses,
+  generated workflow tiers, and functional OIDC are removed.
+- Users authenticate with supported providers through `/login` and select models through `/model`.
+- Workflow model selection remains owned by dynamic-workflows, without HUMAIN-generated tiers or profile routing.
+- Local, explicit non-SSO `humain-code`, and DeployNow provider registrations remain available through the normal
+  model registry.
+- `HUMAIN SSO` remains visible in `/login` without models or a model API endpoint, and every credential operation
+  rejects with `HUMAIN SSO is not supported yet.`
+- The `hc` executable alias, HUMAIN theme, and Forge startup cwd support remain.
+
+Rows below that mention `/hc`, profiles, Forge prompt context, generated tiers, product status, or functional SSO
+describe the 2026-07-01 snapshot only. Use the current architecture and flow documents for present behavior.
+
+## Summary
+
+Overall architecture score: **7.8/10**.
+
+The package shape is directionally sound:
+
+- `packages/ai` owns provider transport.
+- `packages/agent` stays model-agnostic.
+- `packages/tui` owns rendering and input primitives.
+- `packages/coding-agent/src/humain` owns HUMAIN Code and Forge product behavior.
+- DeployNow model bindings enter as normal provider registrations.
+
+The main confirmed risks are enforcement gaps, not a collapsed architecture. Lower generic packages still contain
+some HUMAIN or DeployNow product references, auth/status/request-auth semantics are not consistently described by
+one predicate, session export path resolution needs tightening, and architecture boundaries are not yet enforced by
+`npm run check`.
+
+## Scoring Rubric
+
+| Score | Meaning |
+| --- | --- |
+| 9-10 | Clear ownership, enforced by tests or checks, low leakage risk. |
+| 7-8.5 | Sound design with localized leaks, missing automation, or bounded complexity pressure. |
+| 5-6.5 | Works today but relies on convention, duplicated semantics, or manually maintained agreement. |
+| Below 5 | Boundary confusion, unsafe defaults, or broad untested behavior. |
+
+## Component Scores
+
+| Component | Score | Status | Evidence | Required fixes or mitigations |
+| --- | ---: | --- | --- | --- |
+| Package boundary model | 7.5/10 | Aligned but mostly convention-enforced. | Layer contract in [architecture](humain-code-forge-architecture.md#layer-ownership); lower package product hits found in provider/TUI source. | Add an architecture boundary check and wire it into `npm run check`. Keep HUMAIN/Forge behavior concentrated in `src/humain`. |
+| `packages/ai` provider transport | 7/10 | Correct owner for provider APIs, with product-name leakage. | Bedrock transport belongs in [`bedrock-converse-stream.ts`](../../ai/src/api/bedrock-converse-stream.ts); HUMAIN cache env reads exist in OpenAI, Anthropic, and Bedrock APIs. | Move HUMAIN env translation to the coding-agent/provider config boundary. Replace DeployNow-specific transport comments with provider-neutral wording. |
+| `packages/agent` loop | 9/10 | Strongly aligned. | Agent execution uses injected stream behavior in [`agent-loop.ts`](../../agent/src/agent-loop.ts). | No confirmed fix. Keep `/hc`, Forge env parsing, and provider policy out of this package. |
+| `packages/tui` rendering/input | 7.5/10 | Mostly aligned, with branded env leakage. | TUI owns terminal primitives; `HUMAIN_TERMINAL_TUI_WRITE_LOG` is read in [`terminal.ts`](../../tui/src/terminal.ts). | Move branded env mapping above TUI, or expose a generic config option such as `writeLogPath`. |
+| `packages/coding-agent/src/main.ts` startup wiring | 8/10 | Acceptable public distribution boundary. | Startup cwd and HUMAIN extension injection are described in the [flow walkthrough](humain-code-forge-flow-walkthrough.md#flow-1-startup-and-cwd-resolution). | Keep this file as wiring only. Do not add Forge provider policy here. |
+| Core session/runtime services | 8/10 | Generally aligned. | Runtime services are cwd-bound in the [flow walkthrough](humain-code-forge-flow-walkthrough.md#flow-2-settings-trust-and-resources). | Resolve relative `exportToJsonl()` paths against the session cwd, not `process.cwd()`, and add focused coverage. |
+| Resource loading and trust | 8.5/10 | Aligned. | Project resources are trust-gated in the resource-loading flow. | No confirmed fix. Keep project `.humain-terminal` resources behind trust and avoid implying sandboxing. |
+| Extension runtime | 8/10 | Aligned if documented as trusted code. | Extension provider registration and hooks are normal extension runtime behavior. | Treat extensions as trusted code. Do not present them as process, filesystem, network, or credential isolation. |
+| Settings/auth/model registry | 6/10 | Weakest architecture score. | Request auth can include provider headers and env, while some availability/status paths remain API-key-shaped. | Define one auth capability predicate and apply it to availability, status display, model selectors, runtime overrides, and request auth. |
+| Provider request path | 7.5/10 | Mostly aligned. | Provider-scoped env flows from model registry into `streamSimple()` in the request path. | Either make header/env-only auth first-class with tests, or reject it consistently at provider registration. |
+| HUMAIN/Forge extension | 8/10 | Correct owner with complexity pressure. | HUMAIN extension owns `/hc`, Forge cwd detection, profiles, DeployNow descriptors, provider registration, status, and workflow tiers. | Validate or warn on `/hc create-profile` when the provider/model is unavailable. Split `src/humain/index.ts` by concern when growth justifies it. |
+| DeployNow descriptors and fail-closed behavior | 8/10 | Aligned. | Bedrock/OpenAI/Anthropic descriptors and explicit provider fail-closed behavior are covered in `humain-forge-extension` tests. | Add diagnostics for incomplete explicit `FORGE_RUNTIME_MODEL_PROVIDER` configs. Keep descriptors documented as route descriptors, not secrets. |
+| SSO / model API separation | 9/10 | Strongly aligned. | Non-SSO HUMAIN Code and DeployNow providers can register without requiring `/login`. | No confirmed fix. Keep `/login` separate from model API provider registration. |
+| Docs and tests as architecture evidence | 6.5/10 | Useful but not yet enforced. | Architecture docs, flow docs, and focused tests exist, but no architecture ratchet is wired into root checks. | Land this docs set, add `check:architecture`, and add docs/source checks for env names, provider names, `/hc` command names, and cited tests. |
+| Package metadata and branding | 8/10 | Aligned with an ambiguity to clarify. | Public CLI is HUMAIN-branded while package/import names remain upstream-compatible. | Add an SDK/install note that npm package and import names intentionally remain upstream-compatible until a deliberate package-scope migration. |
+
+## Required Fixes
+
+These are confirmed architecture issues, not just style preferences:
+
+1. Add `check:architecture` and wire it into `npm run check`.
+2. Move branded HUMAIN env handling and DeployNow references out of generic `packages/ai` and `packages/tui`
+   source, or explicitly allowlist narrowly justified compatibility aliases.
+3. Fix auth/status/request-auth consistency with one shared capability predicate.
+4. Update tests after moving branded env handling, especially cache-retention coverage that currently lives in
+   generic provider tests.
+5. Resolve relative `exportToJsonl()` paths against the session cwd and add a regression test.
+6. Add diagnostics for incomplete explicit Forge provider configs.
+7. Add narrow HUMAIN extension regressions only for uncovered edges, such as invalid profile creation or
+   unintended workflow-tier writes outside Forge.
+
+## Mitigations And Watchlist
+
+- Keep HUMAIN and Forge product behavior in `packages/coding-agent/src/humain`.
+- Keep real provider secret custody outside this repo in Forge, DeployNow supervisor, or auth-broker systems.
+- Keep DeployNow descriptors non-secret even when they are API-key-shaped for compatibility.
+- Keep `/login` separate from model API provider registration.
+- Keep package/import names upstream-compatible unless a deliberate package-scope migration is planned.
+- Do not duplicate existing broad DeployNow registration tests; add targeted tests for missing diagnostics or
+  uncovered branches.
+- Split `src/humain/index.ts` only when doing so reduces real churn across providers, profiles, routing, SSO, or
+  workflow-tier code.
+
+## Suggested Architecture Ratchet
+
+A lightweight first ratchet should fail on new product-specific references in lower packages unless the reference
+is explicitly allowlisted:
+
+```text
+packages/ai/src: no HUMAIN, Forge, DeployNow, deploynow except approved generic compatibility aliases
+packages/agent/src: no HUMAIN, Forge, DeployNow, deploynow
+packages/tui/src: no Forge, DeployNow, deploynow; HUMAIN only through an explicit compatibility allowlist
+```
+
+The ratchet should also check that docs links resolve and that referenced env names, provider names, `/hc`
+command names, and key test files remain present.
+
+## Verification Guidance
+
+For docs-only updates to this scorecard, inspect links and run `git diff --check`. For code changes that address
+the required fixes, follow the architecture doc verification matrix and run root `npm run check` after focused
+tests.