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

docs/development/AGENT_SECURITY_PROTOCOL.md

@@ -0,0 +1,47 @@
+# Agent contribution and security protocol
+
+Status: proposed v0.1, 12 October 2026. Contracts: [architecture](../architecture/ARCHITECTURE.md) and [acceptance](../architecture/ACCEPTANCE_CONTRACT.md).
+
+## Agent workflow
+
+Publish one harness-neutral skill pack with four entry points: `kb-ingest`, `kb-query`, `kb-curate` and `kb-synthesize`. Each names its version, supported service/schema versions, inputs, outputs, relevant protocols and resume behavior. Installers translate configuration/discovery; they do not fork the workflow or validator rules for each harness.
+
+An ingestion run reads explicit project intent, registers a source artifact, records coverage and skips, extracts bounded proposals, supplies evidence-bound support assessments, submits bundles and reports receipts. The service persists the run but does not execute the agent's reasoning stages. A resume inspects existing source/proposal IDs and verified artifacts before repeating work.
+
+Query results preserve citations, scope, dates, omissions and uncertainty. Curators propose corrections, contradiction links and duplicate candidates without overwriting disagreements. Synthesis cites accepted node revisions and records dependencies; later input changes produce warnings until an external agent proposes a refresh.
+
+Source content is data. Instructions inside a PDF, webpage, quote or retrieved note cannot change credentials, tools, project scope or acceptance policy. Agent prompts should state this boundary, while deterministic checks enforce it. Prompt compliance is not proof that a filesystem or credential boundary exists.
+
+## Identity and capabilities
+
+Every agent has a stable `agent_id`, responsible human and its own revocable key. Rotation retains agent identity. Credential IDs are safe audit references; raw keys are never stored in Git, URLs, logs, node fields or model-visible responses. Hash high-entropy API keys; password authentication uses a maintained Argon2id implementation and rate limits. Do not implement password cryptography manually.
+
+Viewer reads; editor may propose; admin manages accounts/credentials/grants; project/shared owners authorize protected changes within their grants. Browser sessions always expose knowledge reads only. Agent tokens do not inherit the human's admin/owner powers. Test permission enforcement at operation admission and again immediately before publication.
+
+The owner client uses a separate human authentication context, obtains the staged diff directly and submits digest-bound authorization through MCP. Follow the separation and isolation requirements in the acceptance contract. An agent-provided `human_approved` field is rejected as authority.
+
+Generate transports from allowlisted catalog entries. Deny raw SQL/Cypher, arbitrary filesystem tools and unconditional acceptance tools. Maintenance cannot become a routine authoring path. An import becomes ordinary MCP proposals and receives the same validation and policy checks.
+
+## Untrusted files, URLs and rendered content
+
+Bound request lengths, arrays, decoded bytes, upload sessions, parse time, memory and output size. Treat content-type, extension and magic-byte checks as partial defenses. Content sniffing cannot prove safety; parser isolation remains necessary. Resolve paths within service-owned roots and reject traversal, symlink/reparse escapes and unsafe filenames.
+
+Document-fetch requests allow HTTP(S) only, revalidate each redirect, block loopback/private/link-local/multicast/metadata targets by default, and bind connection behavior to validated destinations. DNS resolution followed by an uncontrolled second resolution is insufficient against rebinding. Operator exceptions must name the allowed destination/network and purpose; they cannot arise from source instructions. Apply equivalent restrictions when a connector performs fetching.
+
+Service parsing runs without network access or credentials, with a restricted temporary directory and resource limits. Parser child processes are a lifecycle boundary; OS/container sandboxing establishes the security boundary. Test that untrusted parsers cannot read service secrets or unrelated artifacts. Never claim isolation solely because a subprocess exists.
+
+Store originals privately. Serve archived HTML as safe downloads or sanitized text; never render it under the application origin as executable content. Authenticate artifact access just like node access. Retention/rights metadata applies to originals and backups. The absence of project ACLs does not imply public archive access.
+
+Validate MCP origins and hosts, bind local services to loopback, use TLS on hosted endpoints and limit cross-origin access. Keep stdio stdout protocol-only and send redacted diagnostics to stderr. Session IDs are not credentials. Pin and negotiate supported MCP versions; record the provisioned-key profile separately from any future OAuth implementation.
+
+Security source checks: [MCP transport security requirements](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) and [HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), read 12 October 2026. These standards do not by themselves prove GEWU compliance.
+
+## Portable client acceptance
+
+The target harnesses remain Codex, Claude, Antigravity and OpenCode. Record actual application, connector, service and OS versions. Initial pilot coverage may be smaller only when named explicitly. Full v1 must exercise every supported harness and the declared Windows/macOS/Linux portability matrix; a single handshake cannot close those gates.
+
+For each supported pair, verify configuration preserves other servers/skills, correct service/project identity, authenticated source-byte transfer, invalid-evidence rejection, eligible automatic acceptance, exact retry, interrupted-run resume and cited retrieval. Repeat the applicable remote transfer path against the VPS. A VPS cannot read a client-local path.
+
+Use PASS, FAIL, BLOCKED, NOT RUN and UNSUPPORTED with evidence origin and blockers. Separate “configured,” “connected” and “workflow verified.” Symlinks are optional; test a configuration/copy fallback. Uninstall/rollback removes only owned entries and preserves unrelated user state.
+
+No client compatibility or enforced credential isolation is claimed by this document. These are acceptance obligations for implementation.

docs/development/DEVELOPMENT_PROTOCOL.md

@@ -0,0 +1,73 @@
+# Development protocol
+
+Status: proposed v0.2, revised 13 October 2026. Applies to implementation of the [architecture](../architecture/ARCHITECTURE.md). Product requirements remain in the [PRD](../PRD.md). Owner-required modular development is specified in the [module design and replacement protocol](MODULARITY_PROTOCOL.md).
+
+## Work from a bounded contract
+
+Before editing, inspect applicable project instructions, current files and Git status. Preserve unrelated edits. Identify the user-visible result, affected requirement IDs, authority/data boundary, failure behavior and evidence needed to call the slice complete. Use a short task note for ordinary work; reserve an ADR for a durable architectural change. Do not require a new approval cycle for each reversible implementation step already authorized by the user.
+
+Implement one vertical behavior at a time. For example: a source with a wrong-page quote is rejected with a locator finding; an exact retry returns the same outcome; a reader sees the accepted note only after valid submission. Avoid scaffolding the entire roadmap before the first complete flow exists.
+
+Every implementation task names its owning module, public boundary and affected consumers. Design replacement paths as part of the module, including its state/schema compatibility. A folder split alone does not satisfy modularity. Consumers must depend on public contracts and remain independent of a module's storage layout, provider SDK or private helper functions.
+
+## Code ownership rules
+
+| Area | Required behavior |
+| --- | --- |
+| Domain | Own invariants and typed contracts; pure validation where practical. No transport, filesystem or model calls. |
+| Application | Own use-case order, explicit scope, authorization checks, transaction/publication decisions and recovery. |
+| Adapters | Own Git/files/SQLite/parsers/auth mechanics behind bounded interfaces. Never quietly decide policy. |
+| HTTP/MCP | Validate inputs and map outputs/errors; expose only operations in the allowlisted catalog. No duplicate business rules. |
+| Frontend | Read API data, route state and render evidence. No canonical mutation route or hidden browser proposal client. |
+| Local skills | Reason and propose using public contracts. No direct canonical edits, SQL tools or assumed human authority. |
+| Local agent runtime | Own bounded pipeline execution, model/tool dispatch and resumable client checkpoints. Use the service through public MCP contracts; never import its persistence or owner-credential internals. |
+
+The operation catalog declares name/version, request/response schemas, handler, capabilities, permitted transports, idempotency semantics and limits. Test the generated route/tool surfaces, including forbidden exposure. An MCP `readOnlyHint` is documentation, not enforcement.
+
+Use strict typing at new boundaries. Narrow exceptions to actionable domain errors; unexpected failures retain correlation IDs and private traces. Do not return success after a failed required write or check. Use parameterized SQL and subprocess argument arrays. Never interpolate source text, filenames or PR prose into shell commands.
+
+Offload blocking work at one clear boundary. Bound queues and parser/model processes. Do not hold SQLite transactions or the Git writer while waiting for external calls. The durable publication sequence in the acceptance contract takes precedence over a convenient framework background-task helper.
+
+## Frontend engineering
+
+Keep scope, search query, filters and selected node/revision in the URL. Browser back/forward and shared links must restore the intended reading view. Query keys include resolved/requested scope, filters, node/revision and API version as appropriate. Clear private caches on logout or identity changes.
+
+Cancel obsolete requests or ignore their results, including obsolete loading and error states. Query polling exists only for a visible need and cannot overlap indefinitely. Avoid a global real-time event system before the product requires it.
+
+Fetch through the typed API layer. Components receive enough data to render complete states: loading, empty, unavailable, forbidden, stale, index-lagged and successful. A valid empty search is different from a failed request. Profile before adding broad memoization or custom comparison functions. Sanitize Markdown rendering and scope reading typography so source headings cannot restyle navigation.
+
+## Verification proportional to the change
+
+| Change | Minimum evidence |
+| --- | --- |
+| Documentation | Relative-link and consistency checks; no claim of runtime acceptance. |
+| Pure domain rule | Focused tests with valid, invalid and boundary cases. |
+| Scope/auth/catalog | Negative capability tests through actual HTTP and MCP adapters. |
+| Files/Git/proposals | Isolated temporary repositories; replay, conflict and crash/restart tests. |
+| Parsing | Labeled sources with exact location maps and failure states; successful conversion alone is insufficient. |
+| Index/retrieval | Rebuild integrity, explicit scope, ranking/latency fixtures and model-change behavior. |
+| UI | Type/lint/component checks plus browser reading flow, keyboard, narrow layout and screenshot inspection. |
+| Connector/configuration | Preserve unrelated entries, rollback owned changes, and perform the native client workflow. |
+| Module addition/replacement | Public contract tests, dependency/import-boundary checks, consumer integration and an explicit state migration/rollback where applicable. |
+| Agent skill/pipeline | Typed stage fixtures, version pinning, budget/cancellation behavior and resume after an uncertain MCP result; semantic quality uses labeled source examples. |
+| Deployment | Authenticated source-to-reading path on that deployment and a separate restore exercise. |
+
+Use isolated fixtures, fixed clocks and explicit data roots. No unit test reaches live providers or production state. Never overlap tests sharing a mutable SQLite database. Regression tests should demonstrate the failure mechanism, not repeat implementation branches. Cosmetic documentation/UI edits do not justify an invented test suite.
+
+Scaffolding must supply scripts for Ruff check/format, mypy, pytest, TypeScript, ESLint, unit tests and browser tests. Until those scripts exist, do not publish fictional command transcripts. Run focused checks during development, then the affected integration/release gates. Repeat only for changed code, failures or unresolved uncertainty.
+
+Acceptance receipts record revision and dirty-tree baseline, runtime/OS versions, configuration without secrets, exact commands and outputs, fixtures, observed behavior and remaining limitations. Results are PASS, FAIL, BLOCKED, NOT RUN or UNSUPPORTED. User-reported and directly observed results are labeled separately.
+
+## Documentation and change management
+
+Use `docs/decisions/ADR-NNN-short-title.md` for choices that change a public contract, trust boundary, persistence model, deployment topology or dependency family. Include status/date, context, decision, strongest alternative, consequences, migration/rollback and acceptance evidence. Routine implementation details stay with their module or task.
+
+Keep one owner document per rule. Link from the handbook and later from a concise root `AGENTS.md`; thin harness pointers can refer to that file. Do not duplicate rules across CLAUDE/GEMINI/OpenCode copies. Reference project protocols inform decisions but never silently become GEWU instructions.
+
+Write the result and reason first. Distinguish proposed, implemented, tested locally and verified in deployment. Use relative repository links, stable requirement IDs and specific dates. State failures and uncertainty directly. Do not borrow a reference project's metaphors as architecture terminology or present an agent's confidence as measured quality.
+
+Before committing, inspect the exact diff and selectively stage the coherent slice. Commit only when authorized; never stage unrelated work or reset the user's tree. Report local commit, push, deployment and runtime evidence as separate outcomes. Git commits made by the knowledge service follow the stricter acceptance contract and cannot use blanket staging.
+
+## Completion gate
+
+A slice is complete when its behavior and failure cases are implemented, required checks pass, changed contracts/docs are current, and required deployment/client evidence exists. Its module boundary and replacement obligations must also pass the modularity protocol. A blocked client or unrun recovery gate remains visible. Passing unit tests cannot close an untested end-to-end requirement.

docs/development/MODULARITY_PROTOCOL.md

@@ -0,0 +1,66 @@
+# Module design and replacement protocol
+
+13 October 2026. Requirement confirmed by the owner: all development must be modular so each module can be updated or replaced by a better implementation. This protocol applies to the service, local agent, skills, pipelines, connector and frontend. It makes replacement an acceptance criterion.
+
+## Default structure
+
+Use a modular monolith for the service and a separate local-agent application. A module is a coherent responsibility with a public contract, private implementation and declared dependencies. It does not need its own process, repository or package release. Split deployment only when isolation, scaling or independent release needs justify it.
+
+Every feature belongs to a named module. Consumers use its public interface; they cannot import private helpers, inspect its tables, edit its files or rely on provider-specific response objects. Cross-module payloads use GEWU-owned types. The composition root selects implementations and manages their lifetimes. Domain/application code cannot select a concrete implementation through scattered conditionals.
+
+Internal pure helpers may remain functions. Add an interface at a real replaceable boundary, not around every function. Keep stable interfaces small enough that a replacement does not have to emulate unrelated features.
+
+## Required module description
+
+Each replaceable module has a short description beside its implementation, plus a machine-readable descriptor when configuration selects it. The description declares responsibility, public input/output types, errors, owned state, side effects, dependencies, lifecycle and resource limits. The descriptor declares `module_id`, implementation version, provided contract/version, required capabilities, compatible state-schema versions and configuration schema. Resolve exact implementation versions and artifact hashes in the release/run manifest.
+
+Compatibility is behavioral: valid inputs, errors, cancellation, ordering, idempotency and security limits all belong to the contract. Matching method names or a version range alone is insufficient. [Python Protocols](https://docs.python.org/3.12/library/typing.html#typing.Protocol) and TypeScript interfaces describe structure; runtime validators and contract tests enforce exchanged data and behavior.
+
+## Initial replacement boundaries
+
+| Module boundary | Public contract owns | Private implementation / replacement example |
+| --- | --- | --- |
+| Service application use cases | Scope, authorization order, proposal/read outcomes | Reorganize orchestration without changing HTTP/MCP behavior. |
+| Acceptance validators and policy evaluator | Required checks, typed findings, policy/authority bindings | Improve implementation while retaining mandatory evidence and authority invariants. No configurable bypass of those checks. |
+| Canonical repository and publication | Committed reads, expected-head publication, manifests, reconciliation | Git implementation may change behind the port; abandoning Git authority requires an explicit architecture/product change. |
+| Artifact and workflow stores | Immutable hashes, atomic records, resumable upload/run operations | Local filesystem storage can later gain an object-storage adapter. |
+| Source parsers | Immutable extraction artifact and supported locator profile | Replace a PDF parser; keep old extraction artifacts and citations resolvable. |
+| Embedding provider | Normalized vectors plus model/profile metadata | Replace model/runtime; rebuild a separate vector generation. |
+| Search and ranking | Scoped candidates, scores/explanations, revision and budget rules | Replace FTS/vector engine or ranking algorithm without modifying readers. |
+| Identity and credentials | Authenticated principal, capabilities, grants and revocation | Replace login backend without changing proposal authorization semantics. |
+| MCP and HTTP adapters | Versioned wire schemas and domain-error mapping | Update transport SDK without moving rules into routes. |
+| Agent model provider | Typed requests/results, usage, timeouts and declared capabilities | Change local/hosted provider without exposing SDK types to skills. |
+| Agent pipeline runner | Stage dispatch, bounded scheduling, checkpoints and outcomes | Replace orchestration library while preserving stage contracts and resume semantics. |
+| Skills and stage handlers | Declared inputs/outputs, tools, prompt/content versions and budget | Replace an extraction or assessment skill without rewriting the pipeline. |
+| Harness adapter | Profile/skill discovery and authenticated public tool access | Change a host's configuration format without duplicating the skill pack. |
+| Frontend feature modules | Route/data contract, component props, events and accessibility behavior | Replace an evidence viewer or result list while preserving API and navigation. |
+| Design system | Semantic tokens and shared interaction primitives | Revise typography/theme centrally without recoloring feature implementations. |
+
+## Versioning and dependency rules
+
+Public contracts, implementation versions, persisted schemas and model/prompt artifacts have distinct identifiers. Use [semantic versioning](https://semver.org/) for declared stable contracts: compatible additions are minor, fixes are patch, breaking behavior is major. Before 1.0, explicitly list supported contract versions; do not assume every `0.x` update is compatible. Published immutable artifacts are never changed in place.
+
+Backend boundaries use typed ports with injected dependencies; the frontend imports feature public exports and shared primitives. Shared contract packages stay small and have no dependency on providers, storage engines or UI frameworks. Reject import cycles and cross-feature private imports in CI. The local agent cannot import service storage/auth internals; its GEWU access is through the public MCP client contract.
+
+Configuration selects from installed, reviewed implementations by ID. Validate configuration and capability compatibility before activation. Do not discover executable modules from uploaded sources, skill text, arbitrary import strings or URL-supplied code. Python package entry points are a possible future distribution mechanism, not permission to auto-load third-party code; [the packaging guide](https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/) describes discovery mechanisms, not trust enforcement.
+
+Existing deployments use lockfiles and a release manifest. Agent runs additionally pin pipeline, stage, skill, provider and model versions at start. No automatic hot swap in a running acceptance transaction or reasoning stage. A newly selected implementation applies at a controlled deployment/run boundary.
+
+## Replacement workflow
+
+1. Identify the public contract and current behavioral fixtures. Add missing fixtures for the changed boundary before declaring equivalence.
+2. Implement the replacement behind the same port. Compare old/new behavior on representative data; compare retrieval quality, evidence fidelity or performance where the module affects them. A fake adapter proves dependency isolation only, not production equivalence.
+3. Run shared contract tests, consumer integration tests and import-boundary checks. Test required failure states, cancellation and denied capabilities, not only successful outputs.
+4. Migrate state explicitly or build a new derived generation. Record schema compatibility, migration checks and rollback path. Retain old source/extraction versions and accepted receipts.
+5. Activate through the composition root/configuration in a test deployment, then complete the affected native client/browser/recovery gates. A compatible swap should require no changes to consumers' business logic.
+6. Roll back by selecting the previous implementation only if it can read the resulting state. Otherwise use the tested state migration/restore procedure. Never claim that changing a version number reverses a destructive migration.
+
+A breaking contract change needs an ADR, explicit consumer migration, version negotiation where relevant, and a declared deprecation window. Replaceability does not imply every future technology will fit today's contract; preserve the product invariants and document the actual compatibility cost.
+
+## Required evidence
+
+At scaffolding, add import/dependency checks and reusable contract test suites for the first real boundaries. Each new module must demonstrate isolated testing with collaborators substituted through public ports. Each replacement must demonstrate a swap without unrelated module edits, or declare the contract migration that makes those edits necessary.
+
+Early acceptance examples: swap an embedding provider and rebuild without changing search consumers; substitute an extraction-stage implementation while preserving old citations; replace a frontend evidence panel without changing the read API; resume an agent run with its original pinned skill version after a newer version is installed. These are required design tests to implement, not existing passes.
+
+Primary documentation above was checked on 13 October 2026. No module implementation or replacement test exists yet.

docs/development/OPERATIONS_PROTOCOL.md

@@ -0,0 +1,43 @@
+# Operations and recovery protocol
+
+Status: proposed v0.1, 12 October 2026. Applies to local and VPS installations of the [architecture](../architecture/ARCHITECTURE.md).
+
+## Installation identity and health
+
+Each installation has a stable service ID, environment label and one authoritative knowledge ref. Diagnostics report software/schema versions, canonical head, indexed revision, index lag, pending queue count/age, parser availability, model/index profile and configured limits. Return only the caller's permitted identity/capability details. Public liveness must not reveal private project names or configuration.
+
+Readiness requires complete startup recovery and available canonical/control stores. An unavailable index may permit explicitly degraded reads but prevents reporting full retrieval readiness. A writer-lock conflict prevents a second instance from accepting writes. Deployment scripts must fail visibly rather than start a competing writer.
+
+Use structured, bounded logs with request, run, proposal and safe credential identifiers. Redact before persistence. Never log source bodies, full tool payloads, passwords or authorization headers by default. Record safe error codes and private stack traces with retention limits. Durable acceptance/security audit records have separate retention and backup requirements from disposable diagnostics.
+
+## Backups
+
+Back up a consistent set: knowledge Git repository, artifact/extraction tree, staging/run/receipt tree, private control database, schema versions and required configuration. Keep recovery credentials/encryption keys in a separate protected recovery location. The derived index is optional backup material. A Git remote alone is not an artifact or account backup.
+
+For the first implementation, use a short write-quiescence window: stop new acceptances/uploads/control mutations, drain active publications, checkpoint durable file state, take a supported SQLite backup of the control database, snapshot/copy the matching filesystem set, then resume writes. Record the authoritative Git head and inventory hashes. Do not copy a live SQLite main file while ignoring its WAL.
+
+Encrypt off-host backups and restrict credentials. Proposed starting schedule is daily plus before migration, but owner-selected retention, recovery-point objective and recovery-time objective are prerequisites to team launch. Do not label these values agreed or declare recovery adequate without a measured restore.
+
+Restore into a new isolated directory/host. Verify artifact/extraction hashes, canonical manifests, identity/grants and proposal states, reconcile receipts, rebuild the index and exercise cited reads and a disposable acceptance. Prevent the restored clone from writing as a second authority. After a real rollback, invalidate sessions and reissue/reconcile credentials and revocations before networking is enabled; restoring an older control database must not revive revoked access.
+
+## Schema and model migrations
+
+Version public contracts, canonical records and index schemas separately. A migration declares supported source/target versions, backup prerequisites, dry-run findings, transformed records and rollback limits. Use the same validators as ordinary writes. Canonical migrations create attributable service-maintenance commits; they cannot fabricate knowledge or bypass protected content decisions.
+
+Test migration on a restored copy first. Old readers must reject unsupported schemas explicitly. Rebuild derived indexes into new generations. Keep the previous generation until the new one passes integrity/retrieval checks and old connections drain. An embedding model update cannot mix vector dimensions or silently erase citations to old source extractions.
+
+Rollback of knowledge uses a corrective/superseding proposal or documented maintenance recovery, preserving history. Never solve an application bug by silently rewriting accepted Git history. Software rollback must remain compatible with the resulting schema, or restore the complete consistent snapshot under a stopped service.
+
+## VPS transfer and release
+
+Freeze local writes, record the final head, transfer and verify all authoritative stores, restore the service under a restricted account, then run its local health/recovery checks. Test HTTPS, cookie/key boundaries and MCP transfer from an actual client. Switch client endpoint configuration after the VPS is ready. The old local service stays read-only/offline until deliberately made authoritative again through a controlled handback.
+
+The web and MCP routes share domain logic but retain different capabilities. Built UI assets may be served by the Python app behind Caddy. Private data mounts are never exposed as a static directory. Parser processes have restricted mounts; the public service runs without host-admin privileges. Record container/image digests and exact lockfiles used for the release.
+
+Release evidence separates local checks, pushed revision, deployed revision, authenticated runtime behavior and restore verification. No deployment command or backup schedule has been executed as part of this design exercise.
+
+## Capacity and incident handling
+
+Before team release, name benchmark hardware, model, corpus, archive sizes, concurrent users/agents, queue limits and query budget distribution. Measure latency percentiles, top-five source recall, cold/warm index rebuild, parse time, memory and disk growth. PRD targets remain search under 300 ms at 10,000 project nodes, 100,000 total nodes and rebuild under ten minutes; define the measurement setup before running it. Saturation returns a retryable bounded outcome rather than unlimited queuing.
+
+For an incident, inspect persisted production history and the actual affected endpoint/state before proposing causes. Separate observed facts from likely causes and untested hypotheses. Preserve the failed record, isolate a reproducer, repair the boundary and add a regression fixture when justified. Never infer deployed state from a local checkout or hide invalid evidence behind a successful request status.

docs/development/VISUAL_DESIGN_PROTOCOL.md

@@ -0,0 +1,84 @@
+# Visual design protocol
+
+Direction: editorial research workspace, selected by the owner on 12 October 2026. Status: proposed implementation specification v0.1. Exact colors, typefaces and geometry require a rendered review.
+
+## Artistic and functional premise
+
+The interface should feel like working with a well-edited research folio: a warm page, strong titles, legible annotations and precise references. Its central visual relationship is between an assertion and the evidence beside it. Project context stays visible while the reader moves between a problem, an approach and its source.
+
+Use the editorial/technical typography contrast from Sonification, adapted for sustained reading. Large titles can carry character. Operational labels remain quiet and readable. Space and thin rules organize the page; dense technical metadata appears when it helps the reader assess origin, freshness or a relationship.
+
+The website searches, navigates and displays knowledge. It has no capture, edit, approve, merge or generate controls. Account sign-in and view preferences do not change that knowledge boundary.
+
+## Information architecture
+
+Primary destinations are Search, Problems & topics, Sources and Stale knowledge, within an explicit project or all-projects scope. A project landing view shows its owner-defined purpose and key questions before recent records. Avoid a dashboard of counts without a reading task.
+
+The core journey is: choose scope -> find a problem or note -> inspect applicable approaches and their conditions -> open the supporting quote -> inspect the source revision. History and typed neighbors are available without taking over the reading surface. Accepted relationships and similarity suggestions occupy separately labeled sections.
+
+Desktop uses a modest navigation rail, a flexible reading/results area and an optional evidence panel. Target a 224 px rail and a 360–440 px evidence panel where space permits; the reading column has a maximum measure of about 68 characters. At insufficient width, evidence becomes a route or drawer and navigation collapses. Do not force three columns into a narrow viewport or hide primary reading content to preserve panel dimensions.
+
+At 390 px, use one natural document flow. Search filters open on demand; citation links navigate to a focused evidence view with an obvious return path. At 200% zoom, preserve content and function. Long IDs/URLs wrap or offer a labeled copy action. Data tables may have a local horizontal scroll region with headers; the page itself must not overflow.
+
+## Proposed visual tokens
+
+Light theme is the initial acceptance target. A dark theme is a later token variant requiring its own contrast and screenshot checks, not a color inversion.
+
+| Token | Proposed value | Role |
+| --- | --- | --- |
+| `surface.canvas` | `#F4F1EA` | Warm page background. |
+| `surface.paper` | `#FFFDF8` | Reading/evidence surface. |
+| `surface.subtle` | `#EAE5DA` | Quiet grouping and selected rows. |
+| `text.primary` | `#242722` | Main reading text. |
+| `text.secondary` | `#596057` | Secondary content, still readable. |
+| `border.subtle` | `#D6D0C3` | Decorative separators only. |
+| `border.control` | `#777C71` | Control boundaries where required for recognition. |
+| `accent.link` | `#315D50` | Links, focus and active scope. |
+| `status.caution` | `#85520B` | Stale or incomplete context, always labeled. |
+| `status.error` | `#A1342B` | Failed/unavailable states, always labeled. |
+
+These are candidate foreground/background pairs. Verify their actual rendered use; a palette list is not accessibility proof. Never lower text opacity to suggest age. Superseded content retains reading contrast and a clear status label.
+
+Use semantic CSS properties once in the token layer; components cannot invent hex colors, spacing scales or animation durations. Spacing scale: 4, 8, 12, 16, 24, 32, 48 and 64 px. Typical radii: 2–6 px. Use shadows for overlays only. Thin rules and typography establish ordinary hierarchy.
+
+Proposed fonts: Source Serif 4 for editorial titles and long-form reading; Source Sans 3 for navigation, search results and controls; JetBrains Mono for IDs, code and compact technical values. Self-host licensed assets with local fallbacks and `font-display: swap`. Verify Cyrillic and any required CJK fallback coverage with the actual source corpus. Font choice must not create a network dependency for local/offline reading.
+
+Reading text begins at 17–18 px with roughly 1.6 line-height. Controls and result descriptions use 16 px; secondary metadata uses at least 14 px. Use sentence case. Small uppercase may identify a short section, but must never carry the main content or hide warnings. Dates/numeric tables use tabular figures.
+
+## Component contracts
+
+| Component | Must communicate | Interaction/state requirement |
+| --- | --- | --- |
+| Scope selector | Current project, included shared/cross-project scope | Changing scope updates URL and query; hidden exclusions are disclosed. |
+| Search result | Title, concise assertion/summary, origin, relevant dates and evidence availability | Full title is a link; keyboard focus visible; stale warning survives truncation. |
+| Reading header | Node type/title, project, lifecycle and dates | Keep revision/history discoverable without showing raw schema jargon by default. |
+| Evidence block | Exact quote, source title, location, captured revision and availability | Opens the cited revision/location; explains when preview is unavailable; original/download remain permission-checked. |
+| Support details | Location check, semantic assessment, source reliability and assessor | Separate labels; never collapse into a green “verified” badge. |
+| Relationship row | Typed verb, target, conditions and support/rationale | Distinguish accepted link from related suggestion; omit out-of-scope target content with an explanation. |
+| Freshness notice | As-of date and why stale/unknown | Text plus icon; no color-only indication. |
+| History | Previous revision, actor category, date and reason | Reading old material visibly retains its revision context. |
+| System state | Loading, empty, failed, forbidden, offline or index behind | Give the correct next action; do not label request failures as “No results.” |
+
+Source quotations must look like quotations. Interpretation text must be labeled as interpretation and retain its supporting references. A model's confidence is not a truth probability; expose its meaning in details rather than presenting a spurious percentage meter.
+
+Use a small application-owned component catalog: AppShell, ScopeSelector, SearchField, FilterBar, ResultRow, ReadingHeader, EvidenceBlock, SourceLocator, RelationshipRow, FreshnessNotice and StateMessage. Build each with fixtures for long titles, missing metadata and failure states before composing large pages.
+
+## Motion, accessibility and content safety
+
+Frequent search, selection and keyboard navigation should respond immediately. Optional disclosure transitions are brief, typically 120–180 ms, and respect reduced-motion preferences. No animated text entrance, CRT fringing, pulsing telemetry, scanlines or decorative graph animation in the reading surface.
+
+Use semantic HTML, logical headings, landmarks and a skip link. All interactions work by keyboard. Dialogs trap focus and restore it on close; non-modal panels do not trap focus. Announce asynchronous result counts and errors without moving focus unexpectedly. Copy actions have visible success/failure feedback.
+
+Target WCAG 2.2 AA: normal text contrast at least 4.5:1; large text and meaningful control graphics at least 3:1 where applicable. GEWU's preferred touch target is 44 x 44 CSS px, a product standard stricter than the AA minimum target-size criterion. Do not claim this preference is the universal WCAG minimum. See [W3C's criterion reference](https://www.w3.org/WAI/WCAG22/quickref/), checked 12 October 2026.
+
+Render source Markdown as untrusted content. Disable raw HTML by default, sanitize any supported extensions, and do not execute source scripts or MDX. Source CSS cannot enter the application styles. Code and formulas have bounded rendering and horizontal scrolling where needed. Downloads use controlled, authenticated routes; embedded previews have an explicit sandbox policy.
+
+## Visual acceptance
+
+Before a page is called complete, inspect real renders at 1440 x 900, 1024 x 768 and 390 x 844, plus 200% zoom and a 320 CSS-pixel reflow case. Exercise keyboard-only scope -> search -> node -> quote -> return, and test a screen reader on the primary path. Run axe, then manually check reading order, focus restoration and meaningful labels; an automated score alone cannot establish accessibility.
+
+Use fixtures for: long multilingual titles, missing archive, scanned PDF extraction failure, unsupported claim draft outside accepted results, stale datapoint, superseded node, contradiction, cross-project omission, empty search and index lag. Verify contrast on actual states, including selected/hover/focus/disabled appearances.
+
+Record screenshots with route, fixture, viewport, revision and browser version. Evaluate whether a person finds a cited answer within the PRD's two-minute target. Screenshots prove layout at those dimensions; the reading task measures usefulness. Neither substitutes for the other.
+
+This document specifies direction and review criteria. No rendered GEWU page or accessibility pass exists yet.