GEWU/docs/README.md

# GEWU architecture and engineering handbook

Started 12 October 2026; revised 14 October 2026. Architecture proposal v0.3. The backend, authenticated HTTP/MCP workflows, a read-only research UI, and a modular GEWU agent pack are implemented to varying levels of local verification. Consult the [implementation status](IMPLEMENTATION_PLAN.md#implementation-status-14-october-2026) and [acceptance ledger](acceptance/ledger.md) for evidence and open gates.

**Tagline:** Investigate. Connect. Remember.

GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Interpretations vary; the name evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse. GEWU is a shared research library with a read-only website and an MCP contribution workflow. The [goal](GOAL.md) and [PRD](PRD.md) own product requirements. This handbook translates them into a proposed implementation and working protocols. It does not change their priorities or claim that M0 is complete.

## Read in this order

For a local setup and first browser session, start with the [getting started guide](GETTING_STARTED.md). It uses a disposable synthetic registry and does not claim pilot qualification.

Start delivery planning with the [implementation plan](IMPLEMENTATION_PLAN.md): work packages, pilot/full-v1 boundaries, decision gates and PRD traceability.

For the project knowledge UI, use the [knowledge browser implementation plan](KNOWLEDGE_BROWSER_PLAN.md): Luna's handoff for browsing, node details and cross-links, and graph exploration.

1. [Reference review](reviews/ARCHITECTURE_REFERENCE_REVIEW.md): which practices to borrow, adapt or reject.
2. [Architecture](architecture/ARCHITECTURE.md): components, technology choices, alternatives and deployment.
3. [Acceptance and evidence contract](architecture/ACCEPTANCE_CONTRACT.md): records, authority, replay, crash recovery and source integrity.
4. [Development protocol](development/DEVELOPMENT_PROTOCOL.md): implementation workflow, module boundaries, verification and documentation.
5. [Visual design protocol](development/VISUAL_DESIGN_PROTOCOL.md): the owner-selected editorial research direction and its review gates.
6. [Agent and security protocol](development/AGENT_SECURITY_PROTOCOL.md): agent workflows, permissions, untrusted inputs and client acceptance.
7. [Operations protocol](development/OPERATIONS_PROTOCOL.md): persistence, deployment, backup, migration and incident response.
8. [Local agent](architecture/LOCAL_AGENT.md) and [source pack](../agents/gewu/README.md): RESEARCH-style workspace profile, modular skills and pipeline procedures.
9. [Module replacement protocol](development/MODULARITY_PROTOCOL.md): public contracts, dependency boundaries, replacement tests, state migration and rollback.

The [independent architecture review](reviews/ARCHITECTURE_SENIOR_REVIEW.md) records findings and corrections for the v0.2 acceptance foundation. The [local-agent and modularity addition](reviews/LOCAL_AGENT_MODULARITY_REVIEW.md) records the v0.3 scope and verification separately.

The project knowledge browser implementation and remaining acceptance work are tracked in the [knowledge browser plan](KNOWLEDGE_BROWSER_PLAN.md) and [acceptance note](acceptance/2026-10-16-knowledge-browser.md).

## Decision status

| Status | Meaning here |
| --- | --- |
| Product requirement | Already stated in GOAL/PRD; this proposal must satisfy it. |
| Owner-selected direction | Warm editorial research workspace, confirmed in this conversation. Exact tokens and layouts remain proposed. |
| Owner-required additions | Custom local agent in the RESEARCH workspace style; modular development across all components with tested replacement paths. |
| Architecture recommendation | Concrete engineering default for review; no implementation or measured acceptance implied. |
| Open owner decision | A policy, staffing, capacity or content choice that engineering cannot present as approved. |

Protocol language describes the intended implementation standard if this baseline is adopted. The reference projects' instructions have no authority over GEWU. Repository-specific Symbia consultations, agent-hook behavior, terminal aesthetics and approval requirements were reviewed as source material rather than activated.

## Next implementation boundary

The disposable local vertical slice now uploads a selected source through MCP, validates and accepts an evidence-backed note under a test policy, reads the committed revision, and opens its citation in the browser. Retry, recovery and scoped-read cases have local tests. The test policy is not the production policy. Remaining work includes real pilot source and question qualification, protected owner authorization, selected native-client workflows, portability and accessibility acceptance; see the implementation plan and ledger for the next gates.

Before that boundary becomes a pilot deployment, settle the open decisions listed in the architecture. Implementing a smaller slice does not reduce the PRD's full-v1 requirements for hybrid retrieval, supported source formats, four agent harnesses and portable operation.

Runtime versions are locked in the Python and web workspaces. The agent pack has a contract/version manifest, local checkpointing, and an additive installer; native-client discovery and workflow acceptance remain open. The service exposes authenticated reads and contribution workflows, and the browser reads accepted knowledge with citations. Pilot corpus evaluation, protected owner authorization, cross-platform qualification, deployment, and accessibility gates remain open. Skill-file validation is separate from installed discovery and live workflow acceptance.