feat: add documentation, specifications, and pipeline configurations for GEWU agent system

docs/reviews/ARCHITECTURE_REFERENCE_REVIEW.md

@@ -0,0 +1,43 @@
+# Architecture and protocol reference review
+
+12 October 2026. Scope: current local documents supplied by the owner, compared with GEWU PRD 0.7 and GOAL. This is a document review, not a live acceptance audit of AAA, Jev or Sonification.
+
+## Finding
+
+Borrow explicit contracts, clear module ownership, durable evidence and careful frontend lifecycle management. GEWU's product boundary requires a smaller runtime than AAA and a stronger acceptance boundary than an advisory agent router. Reference rules are evaluated individually; their status labels and imperative wording do not make them GEWU instructions.
+
+## Reference inventory and disposition
+
+Paths below identify the local source material under `D:/01_GIT/`. They are provenance labels, not required cross-repository dependencies. Portable GEWU protocols live in this repository and do not require those files at runtime.
+
+| Reference | Keep or adapt | Do not carry into GEWU |
+| --- | --- | --- |
+| `AAA/docs/development/practices/SCAFFOLDING_AND_DEVELOPMENT_RULES.md` | Explicit tiers, bounded schemas, central composition/lifecycle, isolated tests and documented gates. | Cognitive ProcessingModule/daemon scaffolding; blanket cascade-delete advice; generic BackgroundTasks for critical acceptance; AAA-specific skill mandates. |
+| `AAA/docs/development/practices/BACKEND_BEST_PRACTICES.md` | Short transactions, bounded concurrency, upload/SSRF defenses, structured safe errors, typed new code and private diagnostics. | Copying thread-local connection decorators into async work; per-conversation locking as a substitute for a global canonical writer; assuming threads isolate hostile parsers. |
+| `AAA/docs/development/practices/FRONTEND_BEST_PRACTICES.md` | URL state, request/subscription cleanup, demand-driven work and scoped source typography. | Blanket memoization and custom comparison rules; a telemetry pub-sub system before measured need; obsolete clipboard fallback as a universal requirement. |
+| `AAA/docs/development/practices/FRONTEND_DESIGN_PRINCIPLES.md` | Consistent shared components, readable list/detail navigation, source sanitization and entity-bound async lifetimes. | Terminal-only typography, tiny 8–10 px labels, hidden chrome rules overriding accessibility, or chat/research authoring workflows. |
+| `AAA/docs/development/proposals/locked_page_artwork.md` | A clear artistic premise tied to specific behavior. | The artwork itself: private-content teasers, text dimming, compressed ghosts and animated accumulation do not serve GEWU reading. |
+| `AAA/docs/architecture/ARCHITECTURE.md` | Lifespan-owned composition root, route/use-case/storage separation and explicit data flow. | Fifteen-stage reasoning pipeline, dream metabolism, internal model orchestration or raw conversation storage as the domain. |
+| `AAA/docs/architecture/DATABASE_SCHEMA.md` | Explicit schema/migration descriptions and qualified verification status. | Its application tables as GEWU's model. Its dated local schema document is not evidence of current production state. |
+| `AAA/docs/architecture/BELIEFS_V2_CONTRACT.md` | Separate encounter/assessment/decision records, digest bindings, explicit authority, immutable assessments and structured missing context. | Human adoption of every record. GEWU explicitly requires eligible automatic acceptance. |
+| `AAA/docs/architecture/BELIEFS_V2_PLAN.md` | Preserve dissent, scope and revisions; similarity alone cannot establish equivalence or support. | Belief mass, participation/dream mechanics or a new internal reasoning layer. |
+| `Jev/.agents/protocols/cross-platform-acceptance-protocol.md` | Per-OS/harness evidence, safe isolated fixtures, explicit result labels and configuration/connection/workflow distinctions. | Treating historical receipts or another client's pass as present compatibility. |
+| `Jev/.agents/protocols/documentation-standard-protocol.md` | Progressive detail, one authoritative home per rule, a navigation hub and relative internal links. | Mandatory `cmd /c`/`%CD%` wrappers described as portable; mandatory metaphors, fixed RFC taxonomy or screenshot counts. Commands must name their shell and be tested. |
+| `Jev/.agents/protocols/style-protocol.md` | Direct prose, concrete mechanisms, explicit limitations and respect for readers. | Mandatory author impersonation, philosophical slogans or rhetorical devices as engineering rules. |
+| `Jev/.agents/protocols/anti-slop-protocol.md` | Remove hype, decorative prose and repetitive document structure while preserving exact constraints. | Word bans that erase useful technical distinctions or measurements. |
+| `Jev/.agents/protocols/system-one-balance-protocol.md` | Context-aware follow-ups, proportionate process and avoiding repeated permission requests for authorized routine work. | Fail-open acceptance/security, model-confidence authority, routing thresholds or hook latency targets. Deterministic evidence and authority gates fail closed. |
+| `SonificationV2/docs/UI_DESIGN_PROTOCOL.md` | Intentional editorial/technical type roles, curated tokens, coherent component grammar and explicit visual review. | CRT fringing/glow, uppercase operational text, tiny controls, DSP meters and instrumentation symbols unrelated to knowledge reading. |
+
+## Contradictions resolved in the proposal
+
+1. AAA's database is operationally central; GEWU requires Git-backed knowledge and a disposable search index. Durable proposals, receipts, artifacts and auth must therefore be explicitly outside the disposable index.
+2. AAA's belief decisions begin with human adoption; GEWU permits routine same-agent support assessments and policy acceptance. Preserve attributable decisions without importing mandatory human review for every note.
+3. Jev's workflow guidance favors routine speed and advisory fallback. In GEWU, search can degrade to keyword mode, but missing evidence or authority cannot degrade into successful acceptance.
+4. The references optimize for agent telemetry and artistic instrumentation. The owner selected warm editorial reading for GEWU. Preserve rigor in evidence presentation while making content readable at ordinary sizes.
+5. Local files support inspectability, but unrestricted agent access conflicts with enforced proposal-only writes. Separate service storage/identity from development and agent execution; report unenforced development mode honestly.
+
+## Resulting documents
+
+The [architecture](../architecture/ARCHITECTURE.md) chooses the proposed stack and runtime boundaries. The [acceptance contract](../architecture/ACCEPTANCE_CONTRACT.md) makes recovery, authority and evidence behavior reviewable. The [development](../development/DEVELOPMENT_PROTOCOL.md), [visual](../development/VISUAL_DESIGN_PROTOCOL.md), [agent/security](../development/AGENT_SECURITY_PROTOCOL.md) and [operations](../development/OPERATIONS_PROTOCOL.md) protocols adapt the useful practices to GEWU.
+
+The existing [implementation-reference review](../LOCAL_AGENT_IMPLEMENTATION_REVIEW.md) remains relevant prior work for Jev/Winnow. Its probes were not rerun here. This review did not inspect or modify production databases or external repositories and does not claim their code implements every statement in their guides.

docs/reviews/ARCHITECTURE_SENIOR_REVIEW.md

@@ -0,0 +1,45 @@
+# Architecture review and revision record
+
+13 October 2026. Artifact: proposed GEWU architecture and engineering handbook, originally drafted under the SKB working name. Repository remains `D:/01_GIT/SKB`. This report covers document-level corrections, not implemented security or runtime acceptance.
+
+## Frozen review inputs
+
+An independent, read-only reviewer inspected the initial proposal, the actual docs-only repository, GOAL and PRD. The initial architecture and acceptance-contract digests were verified before review:
+
+| Artifact | SHA-256 of v0.1 |
+| --- | --- |
+| `docs/architecture/ARCHITECTURE.md` | `353023F13730692C841C6541D4C64BFE6CD206F1D06A17C951638F20FD89083E` |
+| `docs/architecture/ACCEPTANCE_CONTRACT.md` | `EA07DEFA57FCB8333CE46E663D13F24FBC636A46D7FA11E3DDA51CFA0EDF5021` |
+
+The review classified the draft as mixed: product scope and most failure boundaries were concrete, but owner authentication, live receipt recovery, API parity and extraction persistence required further decisions. The findings below describe that frozen draft. Linked documents now contain the revised proposal.
+
+## Findings and corrections
+
+| ID / severity | Original gap | Correction in v0.2 |
+| --- | --- | --- |
+| B1 / blocker before protected-action implementation | Owner MCP authentication had no credential, transport or replay-state contract. Original architecture lines 122–126 and acceptance contract lines 86–95. | [Owner profile](../architecture/ACCEPTANCE_CONTRACT.md#proposed-owner-authentication-profile): controlled HTTPS CLI, separate human reauthentication, short-lived challenge-bound token, owner-only operations, durable decisions and single-use publication binding. This is a custom-client profile with explicit limits. |
+| M1 / major | A committed proposal could have no receipt during a live retry; recovery blocked only the same identity. Original acceptance contract lines 47–78. | [Publication/recovery](../architecture/ACCEPTANCE_CONTRACT.md#publication-and-crash-recovery): deterministic committed manifest, publication journal, immutable receipt, separate dynamic index status, status/retry reconciliation before restart and global publication freeze while required reconciliation fails. |
+| M2 / major | HTTP reads were drawn/described around browser sessions even though the PRD includes agent HTTP retrieval. Original architecture lines 40–56 and 122. | [Public transport contract](../architecture/ACCEPTANCE_CONTRACT.md#public-transport-contract): agent keys may authenticate read HTTP, which shares MCP scope, budgets, revision/error envelopes and cursor semantics. Proposals/owner decisions remain unavailable through the read API. |
+| M3 / major | Extraction blocks/maps and a rebuild watermark were not specified sufficiently to preserve old citations. Original architecture lines 89–106 and acceptance contract lines 105–107. | [Extraction and rebuild](../architecture/ACCEPTANCE_CONTRACT.md#immutable-extraction-format-and-rebuild-procedure): immutable content-addressed block artifacts, code-point maps, exact cited extraction IDs, snapshot head, inventory/profile watermark and isolated generation publication. |
+
+The review preserved the one-writer/CAS topology, manifest-in-commit recovery principle, atomic cross-policy bundles, source/assessment/decision separation, scope rechecks and the editorial visual direction. No evidence warranted adding a graph database, embedded reasoning agent or distributed service architecture.
+
+A bounded independent recheck found B1 and M1–M3 substantively resolved at the design level. It identified one remaining recovery detail: the owner-login seed-encryption key needed its own protected recovery backup. The contract now specifies that backup, restore verification and a disabled-until-re-enrolled fallback when the key is unavailable. Runtime verification remains required.
+
+Primary technical references checked during review: [MCP HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) defines a standards-based OAuth profile; our custom controlled-client profile does not claim that interoperability. [Git update-ref](https://git-scm.com/docs/git-update-ref.html) supports publication conditioned on the expected previous object ID. These sources support mechanisms, not the correctness of an unimplemented service.
+
+## Promoted baseline
+
+The revised [architecture](../architecture/ARCHITECTURE.md) retains Python/FastAPI, React/TypeScript/Vite, private Git-backed canonical records, private source artifacts and derived SQLite retrieval. Engineering protocols remain in [development](../development/DEVELOPMENT_PROTOCOL.md), [visual design](../development/VISUAL_DESIGN_PROTOCOL.md), [agent/security](../development/AGENT_SECURITY_PROTOCOL.md) and [operations](../development/OPERATIONS_PROTOCOL.md).
+
+The changes concentrate detail at four implementation boundaries. They do not settle production auto-acceptance policy, name owners, choose sampling thresholds, supply the evaluation corpus or invent hosting capacity. Those remain explicitly open in the architecture. Exact dependency locks, machine-readable schemas and executable acceptance cases are M0 work.
+
+## Verification scope
+
+Final documentation checks passed across nine files: 38 local links, including four heading anchors, resolved; fenced blocks were balanced and no trailing whitespace was found. `git diff --check` passed, with existing GOAL/PRD line-ending notices. A 76-pattern plain-language scan returned no matches. These are documentation checks, not runtime tests.
+
+The proposed palette was checked numerically against canvas, paper and subtle backgrounds. Text colors had a minimum contrast of 5.17:1; the separate control-boundary color had a minimum of 3.41:1 and is not a text color. These calculations do not establish rendered accessibility, focus behavior or browser layout. No visual page has been implemented or rendered.
+
+Manual prose review preserved technical lists and distinctions rather than removing necessary specification detail.
+
+Existing GOAL/PRD and prior review edits were preserved. Concurrent GEWU naming/intro edits were retained. No commit, dependency installation, source-service implementation, deployment or live harness acceptance is part of this change.

docs/reviews/LOCAL_AGENT_PROBES.json

@@ -0,0 +1,58 @@
+{
+  "date": "2026-10-12",
+  "scope": "Offline isolated probes; temporary state only; no provider calls, host installs or canonical source writes.",
+  "python": "3.10.9",
+  "jev_head": "bca82bb245389dc3ccdcef516878f33b11b71d47",
+  "jev_tree": "dirty implementation snapshot",
+  "winnow_head": "d67763617a5c9f16689332737878e4d81b9c9f99",
+  "checks": [
+    {
+      "check": "registry-handler coverage",
+      "observed": "All 8 declared Jev tools resolve to handlers; not an MCP handshake."
+    },
+    {
+      "check": "missing-reference verification",
+      "observed": {
+        "verified": true,
+        "support_level": "extrapolated"
+      }
+    },
+    {
+      "check": "knowledge write without evidence",
+      "observed": "Direct learn succeeded with empty details and no source/quote validation."
+    },
+    {
+      "check": "keyword-only knowledge retrieval",
+      "observed": {
+        "confidence": 0.69,
+        "context_items": 1,
+        "presentation": "may-apply hint; not ranked multi-result retrieval"
+      }
+    },
+    {
+      "check": "context budget boundary",
+      "observed": {
+        "unit": "characters",
+        "result": "ASSERTION [c",
+        "citation_preserved": false
+      }
+    },
+    {
+      "check": "replay binds operation digest",
+      "observed": {
+        "initial": "acquired",
+        "same_digest": "replay",
+        "changed_digest": "acquired",
+        "limit": "single-process SQLite probe, not concurrent git acceptance"
+      }
+    },
+    {
+      "check": "installer config merge",
+      "observed": "Unrelated MCP entry, theme and existing skill path preserved in an in-memory fixture; no client configuration changed."
+    },
+    {
+      "check": "PDF page-map preservation",
+      "observed": "Mocked two-page extractor output is concatenated without page markers or a location map; no real PDF extraction quality was tested."
+    }
+  ]
+}

docs/reviews/PRD_TARGET_READINESS.md

@@ -0,0 +1,67 @@
+# PRD target alignment and release readiness
+
+12 October 2026. Reviewed working-tree PRD 0.6 against GOAL.md; applied updates in PRD 0.7 and GOAL.md. Earlier reports and unrelated working-tree changes were preserved.
+
+## Assessment
+
+The PRD supports the intended product: a shared knowledge service that preserves evidence and project context, receives contributions from local agents through MCP, and lets people browse without an agent running. Its main remaining obstacle is the acceptance contract. Implementation can begin with a bounded pilot once the first client, source format and policy fixtures are selected. Full v1 is not yet a fixed delivery estimate.
+
+This review inspected the documents in this repository. No application implementation, executable schema or test suite is present. Existing Jev/Winnow probe results are historical reference evidence and were not rerun. This report makes no claim about current external implementations, protocol conformance, performance or deployment acceptance.
+
+## Owner decisions captured in this review
+
+| Decision | Product consequence |
+| --- | --- |
+| Smaller pilot before full v1; retain full v1 commitments | Pilot coverage is recorded separately. Four-client support, listed P0 source inputs and hybrid retrieval remain full v1 requirements. |
+| Dome interactive content and interactive video platform/service | Use these two domains for source fixtures, representative questions and cross-project reuse. Exact registry IDs and sources still need selection. |
+| Up to five people initially | Size the pilot around a small team. This does not specify simultaneous agent count or ingestion throughput. |
+| Admin, viewer and editor roles | Define role permissions now. Editor means MCP proposal capability under the existing read-only website target; this interpretation is explicit in the PRD. |
+| Each local agent has its own API key and identifier | Attribute changes to a server-bound identity; support separate revocation and key rotation without changing the stable agent ID. |
+| Same agent may extract and assess routine notes; record assessments and sample quality | Automatic acceptance can operate without mandatory separate-agent review. Sampling must measure semantic errors independently of quote matches. |
+| Restrict project access to different people later | Keep all-team read access initially and project permissions at P2. Stable principals and explicit ownership support that future change without claiming it is implemented. |
+
+## Findings and applied corrections
+
+| Priority | Finding and document evidence | Update / remaining decision |
+| --- | --- | --- |
+| High | PRD 5.2 puts sources/entities in shared, while the registry and automatic-acceptance section emphasize per-project policies. A project policy alone cannot establish authority over a shared source. | Added shared ownership and policy authority in 5.4. M0 must choose atomic bundles across all affected policies or ordered dependent proposals; partial success must be explicit. |
+| High | PRD 6.3.1 accepts external support assessments but did not decide whether the extractor could assess its own claims. This determines the routine acceptance workflow. | Owner permits same-agent assessment for routine notes. Bound assessments to exact assertions and evidence revisions; quality sampling is required. Sample ownership, cadence and error limits remain open. |
+| High | FR-P8 named capabilities without a concrete initial role or agent-credential model. | Added admin/editor/viewer roles, separate owner authority and per-agent keys/IDs. Required rotation, revocation, current-authorization checks and attribution. Owner authorization and bootstrap still need an M0 mechanism. |
+| High | Architecture permitted delayed indexing without defining how an agent retrieves the node its proposal just accepted. | Separated canonical acceptance from search visibility. M0 must choose canonical reads or a bounded pending response; a committed node cannot appear nonexistent solely because indexing lags. Added receipt reconciliation for a commit-before-receipt crash. |
+| High | M1 required all four clients before M2 ingestion and M3 UI; M4/M5 included P1 work without a distinct full-release gate. | Recorded the approved smaller pilot across M0–M3 and retained full v1 priorities. Added explicit release coverage for recovery, source artifacts, offline operation, budgets, client/OS coverage and VPS handover. |
+| Medium | PRD 6.3.2 required synthesis dependency warnings, but FR-C1 was P1. An implementer could defer warnings along with refresh tooling. | Clarified that displayed accepted syntheses carry P0 warnings; dedicated refresh and compilation workflows remain P1. |
+| Medium | Success metrics used 300 ms, ten minutes, 70% acceptance and cross-agent convergence without sufficient workload, denominator or error definitions. | Added a pre-evaluation decision gate. Existing values remain targets; no hardware, sampling threshold or recovery objective was invented. |
+| Medium | Open questions and examples assumed three starting projects, while M0 asked for two. | Recorded the two confirmed pilot domains, marked IDs as suggestions and kept agentic-design as an example. |
+
+## Recommended pilot and evidence
+
+Start with one local client, one source format whose locations can be preserved, and the two confirmed projects plus shared. Exact selections remain pending. A text-based PDF is a useful candidate if it represents the supplied material; the final fixture should follow the actual research inputs. Build enough read-only UI to find a problem, compare its linked approaches and open their evidence.
+
+The pilot should demonstrate:
+
+1. An editor's registered agent uploads a source and proposes a factual note with a quote, location and recorded support assessment. The service accepts an eligible proposal without human approval.
+2. A viewer finds that note and follows its citation to the exact archived revision while local agents are offline.
+3. The same shared source supports relevant notes in both pilot projects, with origin and requested scope preserved.
+4. Wrong-location evidence is rejected. A correctly located quote that fails to support the claimed year/population is included in the labeled semantic evaluation, so the evaluation measures errors deterministic quote matching cannot catch.
+5. A viewer cannot propose; an agent cannot self-authorize a policy change. Two separately registered agents produce distinguishable audit records. Rotation preserves identity and revocation prevents further authorized work with the old key.
+6. Retrying a proposal creates one acceptance; interruption and recovery preserve its source, decision and receipt. Search publication may lag with an explicit status.
+7. The designated reviewer samples accepted notes and records support errors, corrections and time spent. The sampling plan and pass limits are fixed before measuring the pilot.
+
+These are proposed acceptance cases, not existing tests. The pilot may have narrower format/client/retrieval coverage than full v1. It still needs a complete source-to-reading workflow to test the product's value.
+
+## Decisions still needed
+
+| Decision | Recommendation | Needed by |
+| --- | --- | --- |
+| Initial client, source format and real material | Pick the team's most-used client and a representative source format; collect sources and answerable questions for both projects. | Pilot fixture selection |
+| Shared ownership and first admin/project owners | Name the initial responsible people; specify protected-action authentication separately from agent keys. | M0 authorization contract |
+| Quality sampling | Assign a human reviewer initially and agree sample size, cadence, semantic-error limit and correction/escalation response. This is a recommendation, not a confirmed staffing decision. | Before pilot evaluation |
+| Concurrent agents and hosting | Specify simultaneous runs, typical/max source size, storage budget, VPS capacity, backup owner and recovery objectives. Five human users alone does not define service load. | Before performance and hosting acceptance |
+| Exact auto-acceptance matrix | Specify eligible types for project and shared records, interpretation/relationship rules and exceptions. | Before acceptance implementation |
+| Bundle/recovery contract | Choose cross-policy transaction behavior, proposal revision/state transitions and accepted-revision read behavior. | Before service persistence implementation |
+
+Optional brief tooling, graph canvas, rich comparison views and project-restricted access remain later work under their existing priorities. No launch expansion is implied by this review.
+
+## Change and verification record
+
+Updated PRD to 0.7, aligned GOAL.md with the owner's pilot decisions, and linked this report from the earlier review. Preserved the earlier implementation-reference review and probe artifacts. Documentation checks cover local Markdown links, unique requirement IDs and consistency of the newly recorded decisions. There is no runtime verification or commit in this review.