Zacharon · Oct 17, 2026 · Oct 17, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -1,4 +1,7 @@
 * -text
 # Preserve the existing byte policy; recognize CRLF as valid in this new revision.
 /distribution/agentic-engineering-os-2026.10.09-public.2/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+/distribution/agentic-engineering-os-2026.10.09-public.3/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
 /distribution/agentic-engineering-os-2026.10.12-public.4-candidate.1/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+/distribution/agentic-engineering-os-2026.10.17-public.4/** -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
+/site/architecture.html -text whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol
diff --git a/README.md b/README.md
@@ -6,9 +6,13 @@ This repository contains neutral templates, reusable tools and an authored synth
 
 ## Try it
 
-Download the [setup archive](site/downloads/agentic-engineering-os-2026.10.09-public.2.zip), or use the [unpacked package](distribution/agentic-engineering-os-2026.10.09-public.2/README.md). Follow the [corrected first-run guide](site/first-run.html): public.2's bundled FIRST_RUN.md has a known relative-output defect. The guide resolves the output path absolutely while preserving the traversal guard. The demo ingests a source, creates a pending knowledge proposal, prepares a handoff, checks a sample result and rejects stale or missing context. It makes no model calls and does not apply Gold knowledge.
+Download the current [public.4 setup archive](site/downloads/agentic-engineering-os-2026.10.17-public.4.zip), or use the [unpacked package](distribution/agentic-engineering-os-2026.10.17-public.4/README.md). Follow its [FIRST_RUN.md](distribution/agentic-engineering-os-2026.10.17-public.4/FIRST_RUN.md). The demo ingests a source, creates a pending knowledge proposal, prepares a handoff, checks a sample result and rejects stale or missing context. It makes no model calls and does not apply Gold knowledge.
 
-CPython 3.14.5 is required; Windows with CPython 3.14.5 is tested. Install the package's documented requirements into a fresh virtual environment. Git is needed for the Librarian's approved apply/rollback path. Other platforms and provider handoffs are unverified.
+Requires Python 3.11+ (tested on 3.11.15 and 3.14.5 on Windows). Install the package's documented requirements into a fresh virtual environment. Git is needed for the Librarian's approved apply/rollback path. Other platforms and provider handoffs are unverified.
+
+## How research becomes trusted knowledge
+
+**Bronze** keeps raw source material and where it came from. An agent can collect it, but source text is evidence, not instructions. **Silver** is a proposed knowledge note drafted from Bronze with its source, diff and checks; it remains unapproved. The **owner decision** is a human accepting, editing or rejecting that exact proposal. **Gold** is the approved note applied to the project's trusted knowledge after the required fresh checks and Git checkpoint. Agents can prepare Bronze and Silver; only the owner can authorize Gold. The synthetic demo stops at pending Silver.
 
 ## Explore the system
 
@@ -20,10 +24,12 @@ CPython 3.14.5 is required; Windows with CPython 3.14.5 is tested. Install the p
 - [First run](site/first-run.html)
 - [Capabilities and verification](site/verification.html)
 - [Source credits](site/sources.html)
-- [Public-safe verification receipt](site/verification-public.2.json)
+- [Current public.4 verification receipt](site/verification-public.4.json)
 
 To view the site locally, run `python -m http.server 4396 --bind 127.0.0.1 --directory site` from this repository and open http://127.0.0.1:4396. Serve only site/, never a personal workspace. The HTML files also open locally.
 
+An owner-private guided walkthrough Site also exists. It requires owner access, so its login-gated URL is omitted from this public README.
+
 The tools prepare and check files; assistant handoffs are manual. No autonomous team, model runtime, provider authentication, native sandbox or hosted service is installed. Mechanical verification, independent review, owner acceptance and release remain distinct.
 
 This is a public source preview, not a paid product release. Pricing, commercial license/distribution terms and support are unset. No open-source license or support commitment is asserted. See the package TERMS-DRAFT.md and SOURCES.md. The repository publication does not deploy the website.
@@ -34,16 +40,9 @@ Created by Zachary Hatch. Copyright (c) 2026 Zachary Hatch. All rights reserved.
 
 See [LICENSE](LICENSE) for the copyright and rights notice. Source credits identify influences and separately installed third-party dependencies; they do not transfer authorship of AEOS or imply endorsement.
 
-## Unpublished first-run repair candidate
-
-The historical download above remains public.2. Its bundled FIRST_RUN has a known relative-output defect. A new [candidate archive](distribution/agentic-engineering-os-2026.10.12-public.4-candidate.1.zip) and [instructions](distribution/agentic-engineering-os-2026.10.12-public.4-candidate.1/FIRST_RUN.md) are prepared for review; publication remains owner-controlled. Extract the candidate into a new folder and run:
-
-```powershell
-python -m venv ../aeos-env
-../aeos-env/Scripts/python -m pip install -r requirements.txt
-../aeos-env/Scripts/python -B scripts/check_package.py .
-$demoOutput = [System.IO.Path]::GetFullPath((Join-Path $PWD.Path '../aeos-first-run'))
-../aeos-env/Scripts/python -B scripts/demo.py --output $demoOutput
-```
+## Historical records
 
-The same absolute-output workaround works with public.2. See [candidate verification and CI](docs/PACKAGE-CANDIDATE.md) and the [release-readiness reconciliation](docs/RELEASE-READINESS-public.4.md) for exact checks, preserved histories and remaining gates.
+- [Public.3 archive](distribution/agentic-engineering-os-2026.10.09-public.3.zip), [first-run guide](distribution/agentic-engineering-os-2026.10.09-public.3/FIRST_RUN.md) and [historical receipt](site/verification-public.3.json) are frozen. Its guide pins CPython 3.14.5; public.4 carries the tested 3.11 compatibility update.
+- [Public.2 archive](distribution/agentic-engineering-os-2026.10.09-public.2.zip) and [historical receipt](site/verification-public.2.json) remain unchanged. Its bundled FIRST_RUN has a known relative-output defect.
+- [Public.1 archive](distribution/agentic-engineering-os-2026.10.08-public.1.zip) and [historical receipt](site/verification.json) remain unchanged.
+- The [public.4-candidate.1 archive](distribution/agentic-engineering-os-2026.10.12-public.4-candidate.1.zip) is a separate, unpublished public.2-lineage repair candidate. Its [candidate record](docs/PACKAGE-CANDIDATE.md) and [October 14 readiness reconciliation](docs/RELEASE-READINESS-public.4.md) are historical and do not describe the current public.3-derived release.
diff --git a/distribution/agentic-engineering-os-2026.10.09-public.3.zip b/distribution/agentic-engineering-os-2026.10.09-public.3.zip
diff --git a/distribution/agentic-engineering-os-2026.10.09-public.3/ARCHITECTURE.md b/distribution/agentic-engineering-os-2026.10.09-public.3/ARCHITECTURE.md
@@ -0,0 +1,114 @@
+# AEOS — architecture and usage
+
+AEOS coordinates project knowledge, bounded context, work, evidence and controlled knowledge updates through saved files and local commands. An operator and assistant follow the documented workflow; the preview does not install an autonomous execution service.
+
+This page describes the public setup package, not the creator's personal operating vault. File links below target the current candidate [public.3 package](README.md). Historical public.1 and public.3 remain separate, frozen revisions.
+
+## How the components connect
+
+Solid arrows represent a file input/output or check implemented by a CLI. Dashed arrows represent an operator/assistant action. Neither style implies a background integration.
+
+```mermaid
+flowchart TD
+    U["Operator + file-capable assistant"] -. "read" .-> R["AGENTS.md → Session Router"]
+    R -. "named project" .-> P["Project Index / State / Next Actions"]
+    R -. "choosing work" .-> Q["Global Next Action Queue"]
+    Q -. "select project" .-> P
+    P --> S["Packet scaffolder"]
+    S --> T["Draft task packet"]
+    U -. "fill scope, checks and authorization" .-> T
+    P -. "select relevant files" .-> C["Explicit context file list"]
+    G["Gold: current research / project notes"] -. "select relevant files" .-> C
+    T --> B["handoff.py build"]
+    C --> B
+    B --> H["Saved bundle: brief + snapshots + hashes + result template"]
+    H --> K["handoff.py check: current sources and bundle integrity"]
+    K -. "copy / give files manually" .-> A["Assistant in its own execution environment"]
+    A -. "authorized task only" .-> X["Tools + named project repository"]
+    X -. "capture actual results" .-> E["worker_result.json + artifacts + checks"]
+    E --> V["validate-result / review / optional complete"]
+    H --> V
+    P --> V
+    V -. "inspect candidate" .-> J["Independent review when required + applicable owner gates"]
+    J -. "controller: authorized factual writeback" .-> P
+    J -. "possible knowledge candidate" .-> L["Librarian propose / verify"]
+    F["Selected source file"] --> I["Librarian ingest"]
+    I --> BR["Bronze source bytes + provenance registry"]
+    BR --> L
+    N["Human / assistant-authored candidate text"] --> L
+    L --> SI["Silver proposal + payload + full diff + checks"]
+    SI -. "owner records exact decision" .-> O["Approved verified proposal + exact Git checkpoint"]
+    O --> AP["Librarian apply --dry-run / apply"]
+    AP --> G
+    SI -. "pending / revise / reject: no Gold write" .-> U
+    V -. "missing / stale / invalid: inspect and rebuild" .-> U
+```
+
+Project writeback and Librarian Gold application are different operations. `proposed_writeback` in a worker result is a suggestion; the handoff adapter never applies it. Librarian verification never supplies owner approval. A passed structural check is not independent review or permission to execute.
+
+## Component contracts
+
+Paths are relative to the package's `vault/`, except package scripts and adapter configuration.
+
+| Component | What goes in → what comes out | How it is used / current status |
+|---|---|---|
+| [Router](vault/00_SYSTEM/SESSION_START_ROUTER.md) | Named task or broad intent → minimum records to read | **Manual / assistant-invoked:** read `AGENTS.md`, then the router. It is Markdown guidance, not a routing process. |
+| [Queue](vault/00_SYSTEM/GLOBAL_NEXT_ACTION_QUEUE.md) and [project records](vault/01_PROJECTS/Sample/PROJECT_INDEX.md) | Priority, scope, state, locks and next actions → selected work and current facts | **Manual:** use the queue to choose among projects; for a named project, read its Index, State and Next Actions directly. No mandatory dashboard hop. |
+| Vault / knowledge notes | Source evidence and reviewed facts → selected context files | **Manual retrieval:** read relevant files and cite their provenance. The preview ships no Wiki search service, vector database or automatic ingestion from URLs. |
+| [Packet scaffolder](vault/09_TOOLS/agent_runner_v1/scripts/build_task_packet.py) | Project records + goal → draft `task_packet.md` | **CLI:** `build_task_packet.py`. Operator fills allowed reads/writes, acceptance checks and actual authorization. A draft is not approval. |
+| [Handoff adapter](vault/09_TOOLS/agent_runner_v1/unified_handoff/handoff.py) | Packet + explicit `--read` selections → bounded copied brief, snapshots, manifest and result template | **CLI:** `build`, `check`, `validate-result`, `review`; `complete` also checks actual scoped changes and rationale. The bundle lives outside the source vault. |
+| [Assistant adapters](config/adapters.json) | Reviewed bundle → actual task result and evidence | **Manual transport:** hand the selected files to your assistant and bring its result back. Configuration describes transports; it does not authenticate providers, launch Codex/Astra or confer permissions. |
+| Verification / continuity | Source hashes, returned result and artifact hashes → candidate validity, current/stale/missing observations and next action | **CLI + human review:** `check` before handoff; `validate-result` and `review` after return. Independent review and owner gates are separate. Fresh sessions read saved files and rerun `review`. |
+| [Librarian](vault/00_SYSTEM/AGENTIC_LIBRARIAN/README.md) | Source bytes + provenance + authored candidate → Bronze, pending Silver, then conditionally Gold | **CLI:** `ingest`, `propose`, `verify`, `inbox`, `apply`, `doctor`, `rollback`. Gold requires an exact owner decision, fresh verified evidence and a covered clean Git checkpoint. The demo stops at pending Silver. |
+| [Kernel ledger](vault/kernel/artifact_ledger.py) | Librarian events → local evidence records | **Invoked by Librarian:** records events; it is not an execution scheduler or a tamper-proof audit service. |
+| [Package checker / demo](scripts/demo.py) | Manifested package + synthetic source → demonstration result, saved commands and continuation files | **CLI:** explicit first-run action. Deterministic Python performs the example; no model, independent reviewer or owner approval is simulated. |
+
+## Plan → Retrieve → Execute → Verify → Learn
+
+```mermaid
+flowchart LR
+    P["Plan<br/>Read project facts<br/>Fill bounded packet"] --> R["Retrieve<br/>Select cited files<br/>Build + check bundle"]
+    R -. "manual assistant handoff" .-> E["Execute<br/>Authorized task<br/>Return result + evidence"]
+    E --> V["Verify<br/>Check result + live sources<br/>Independent review when required"]
+    V -. "authorized controller writeback" .-> L["Learn<br/>Update project facts<br/>Propose knowledge separately"]
+    L -. "next session reads saved records" .-> P
+```
+
+To try the implemented flow, follow [FIRST_RUN.md](FIRST_RUN.md). After installing its prerequisites, from a fresh extraction:
+
+```powershell
+$ErrorActionPreference = 'Stop'
+$aeosParent = Split-Path -Parent $PWD.Path
+$aeosEnvironment = [IO.Path]::GetFullPath((Join-Path $aeosParent 'aeos env'))
+$aeosOutput = [IO.Path]::GetFullPath((Join-Path $aeosParent 'aeos first run'))
+if ((Test-Path -LiteralPath $aeosEnvironment) -or (Test-Path -LiteralPath $aeosOutput)) {
+    throw 'Choose new sibling environment/output names; existing evidence is preserved.'
+}
+python -c "import platform,sys; sys.exit(0 if platform.python_implementation() == 'CPython' and sys.version_info[:3] == (3,14,5) else 'Use CPython 3.14.5')"
+if ($LASTEXITCODE -ne 0) { throw 'Python version check failed.' }
+python -m venv "$aeosEnvironment"
+if ($LASTEXITCODE -ne 0) { throw 'Environment creation failed.' }
+$aeosPython = Join-Path $aeosEnvironment 'Scripts/python.exe'
+& "$aeosPython" -m pip install -r requirements.txt
+if ($LASTEXITCODE -ne 0) { throw 'Prerequisite installation failed.' }
+& "$aeosPython" -B scripts/check_package.py .
+if ($LASTEXITCODE -ne 0) { throw 'Package integrity check failed.' }
+& "$aeosPython" -B scripts/demo.py --output "$aeosOutput"
+if ($LASTEXITCODE -ne 0) { throw 'Demo failed.' }
+```
+
+Open `../aeos first run/START_HERE.md`. The demo ingests a synthetic source, verifies a pending Silver proposal, selects that evidence into a handoff, counts two checked items and saves a candidate result. It then demonstrates refusal of changed and missing sources and restores the synthetic fixture. From the output directory, a fresh process can recover the same candidate:
+
+```powershell
+$aeosParent = Split-Path -Parent $PWD.Path
+$aeosPython = Join-Path $aeosParent 'aeos env/Scripts/python.exe'
+& "$aeosPython" -B vault/09_TOOLS/agent_runner_v1/unified_handoff/handoff.py review --bundle handoff --vault-root vault
+```
+
+For real work, scaffold a packet in your own new vault using the first-run instructions. Give only the approved packet and selected context to an assistant. Return `worker_result.json` and its artifacts, run the documented checks, obtain required independent review and perform only authorized writeback. Contradictory facts require operator reconciliation; a script does not decide which claim is true. Missing evidence stays unknown; stale hashes require inspection and a new authorized bundle, not edited hashes.
+
+## Influences and limits
+
+**ICM** means Interpretable Context Methodology in the recorded [source credits](SOURCES.md). It informs layered files and selective context. It is not a separate runtime between retrieval and execution. Karpathy's **LLM Wiki** informs source-backed notes and compiled knowledge; the local Librarian implements the explicit Bronze/Silver/owner/Gold workflow. It does not install Karpathy's gist or a Wiki connector.
+
+The public preview includes a queue and project templates, but no Operator Dashboard application, MAPS view, general Resume/Restore engine, native sandbox, hosted service, automatic model dispatch or authenticated owner-approval service. Do not infer those features from the creator's personal OS or a conceptual diagram. Refer to the [security repair evidence](SECURITY-REPAIRS.md) for the current candidate's checks and remaining limits; historical acceptance and an archive's existence are not proof a future installation is safe.