docs: add generalized stack implementation guides

Author: nshkrdotcom

.blitz/test_state_v1/indexes/task_states.ndjson

@@ -228,3 +228,33 @@ Expected local contract: `127.0.0.1:7233`, UI `http://127.0.0.1:8233`, namespace
 ## Persistence Documentation
 
 See `docs/persistence.md` for tiers, defaults, adapters, unsupported selections, config examples, restart claims, durability claims, debug sidecar behavior, redaction guarantees, migration or preflight behavior, and no-bypass scope when applicable.
+
+## gn-ten Implementation Guides
+
+OuterBrain is the semantic runtime gateway. It turns language-facing input into
+bounded semantic facts, action requests, quality evidence, and publication
+state without owning product workflow, provider credentials, connector
+execution, or policy authority.
+
+Read these repo-specific guides before changing semantic runtime behavior:
+
+- [Generalized Stack Boundary](https://github.com/nshkrdotcom/outer_brain/blob/main/guides/generalized_stack.md)
+- [QC And Operations](https://github.com/nshkrdotcom/outer_brain/blob/main/guides/qc_and_operations.md)
+
+Operational rules:
+
+- Public interfaces are owned by the `core/outer_brain_*`, prompt/context/
+  memory/guardrail/eval/token packages, bridge packages, and host surface.
+- OuterBrain may consume Citadel authority facts and GroundPlane primitives. It
+  must not bypass Citadel for governance, Jido Integration for connectors, or
+  Mezzanine for admitted workflow truth.
+- Provider vocabulary is allowed only as semantic input data, failure
+  classification data, trace facts, receipt facts, or adapter evidence. Generic
+  semantic routing must use manifest, action, authority, and lease refs.
+- OuterBrain does not own GitHub or Linear live commands. If a product or proof
+  command exercises those providers through an OuterBrain path, prefix it with
+  `~/scripts/with_bash_secrets`.
+- Local development uses `mix deps.get`, `mix ci`, package-local tests, and the
+  Mezzanine-owned Temporal workflow only when a cross-repo proof requires it.
+- Evidence is emitted through semantic journal tests, restart-durability
+  receipts, quality/provenance refs, StackLab proofs, and AITrace events.

README.md

@@ -0,0 +1,56 @@
+# OuterBrain Generalized Stack Boundary
+
+## Responsibility
+
+OuterBrain owns semantic-session state, context assembly, prompt and strategy
+shaping, semantic failure carriers, action-request synthesis, provisional/final
+reply publication, restart replay, and quality/provenance evidence.
+
+It does not own product workflow truth, connector SDKs, credential leases,
+governance policy, lower lanes, or primitive persistence semantics.
+
+## Public Interfaces
+
+Primary package groups:
+
+- `core/outer_brain_contracts`, `core/outer_brain_core`,
+  `core/outer_brain_journal`, `core/outer_brain_runtime`,
+  `core/outer_brain_persistence`, `core/outer_brain_restart_authority`, and
+  `core/outer_brain_quality`;
+- prompt, context, memory, guardrail, eval, token, artifact, and optimization
+  packages;
+- bridges for Citadel, typed domains, publication, review, and GroundPlane
+  projections;
+- `apps/host_surface` and proof examples.
+
+## Dependency Rules
+
+Allowed dependencies:
+
+- Citadel contracts for authority and governed route facts;
+- GroundPlane primitives for leases, refs, persistence posture, and projection
+  helpers;
+- AppKit or host-surface DTOs at the northbound edge;
+- AITrace/export contracts for replay and evidence.
+
+Forbidden dependencies:
+
+- direct connector/runtime calls;
+- product workflow mutation;
+- policy decisions that should be made by Citadel;
+- raw provider payloads or private prompt/context bodies in public receipts;
+- unsupervised semantic workers or background tasks.
+
+## Provider Vocabulary Zoning
+
+Provider terms may describe external refusal, adapter unavailability, model
+family metadata, or trace/evidence data. They must not select generic semantic
+control flow. Routing should use stored manifest snapshots, action refs,
+authority refs, and credential lease refs.
+
+## Migration And Cleanup Ownership
+
+OuterBrain cleanup work removes semantic runtime shortcuts, prompt/context
+leaks, stale env access, old atomization hazards, unsupervised task runners,
+and proof-only compatibility paths after the replacement semantic evidence is
+covered by tests and StackLab receipts.

apps/host_surface/mix.lock

@@ -0,0 +1,8 @@
+# OuterBrain Guides
+
+Implementation-facing guides:
+
+- [Generalized Stack Boundary](https://github.com/nshkrdotcom/outer_brain/blob/main/guides/generalized_stack.md)
+- [QC And Operations](https://github.com/nshkrdotcom/outer_brain/blob/main/guides/qc_and_operations.md)
+
+The root [README](../README.md) remains the package and runtime entrypoint.

examples/console_chat/mix.lock

@@ -0,0 +1,54 @@
+# OuterBrain QC And Operations
+
+## Local Commands
+
+```bash
+mix deps.get
+mix ci
+```
+
+Use package-local tests for focused semantic, persistence, prompt, or bridge
+changes, then root `mix ci` before commit.
+
+## Scanner And Proof Obligations
+
+OuterBrain changes must keep these obligations green:
+
+- restart-durability and semantic-session tests;
+- prompt/context redaction and provenance tests;
+- StackLab `examples/outer_brain_restart_durability` and session-lineage proof
+  coverage when semantic replay behavior changes;
+- no Regex usage in touched code/tests;
+- no dynamic atom construction from runtime input;
+- supervised ownership for any process, worker, session fence, publication
+  runner, or background task.
+
+## Secrets And Live Providers
+
+OuterBrain does not read GitHub or Linear secrets. Semantic evidence may refer
+to provider facts through lower receipts, but credential material stays in Jido
+Integration leases and product/live commands.
+
+If a proof command reaches GitHub or Linear through an OuterBrain-backed product
+path, prefix it with:
+
+```bash
+~/scripts/with_bash_secrets
+```
+
+## Tenant, Observability, And Replay
+
+Every semantic journal, publication, failure carrier, and quality evidence ref
+must carry tenant/session/causal-unit scope. Public evidence should expose
+redacted refs, not raw prompt, context, provider, or private reasoning bodies.
+AITrace receives semantic lineage events needed for replay.
+
+## Documentation Checks
+
+After doc edits, run:
+
+```bash
+test -f README.md
+find guides -maxdepth 1 -type f -name '*.md' -print | sort
+git diff --check -- README.md guides
+```