docs: define modular local agent contracts

docs/GOAL.md

@@ -8,9 +8,9 @@ GEWU is a local-first, multi-project knowledge base for people and AI agents. It
 
 ## Core Mission
 
-Help project teams find and reuse trustworthy knowledge without losing its source, scope, freshness, or uncertainty. People search, explore and read knowledge through a read-only web UI. Local agents running in Codex, Claude, Antigravity and OpenCode retrieve cited, budgeted results and contribute exclusively through typed MCP proposals. The service validates and automatically accepts eligible proposals under owner-defined policy; humans do not approve every knowledge change. Development runs locally first, with the shared service deployed to the owner’s VPS afterward.
+Help project teams find and reuse trustworthy knowledge without losing its source, scope, freshness, or uncertainty. People search, explore and read knowledge through a read-only web UI. Local agents running in Codex, Claude, Antigravity and OpenCode retrieve cited, budgeted results and contribute exclusively through typed MCP proposals. GEWU includes a custom local workspace-agent profile with modular skills and pipelines, following the RESEARCH workspace pattern; the selected host supplies its model/runtime. The service validates and automatically accepts eligible proposals under owner-defined policy; humans do not approve every knowledge change. Development runs locally first, with the shared service deployed to the owner’s VPS afterward.
 
-Initially GEWU contains no reasoning agent. It stores original source artifacts or explicit reference-only records, exposes traceable citations, and lets people navigate problems, approaches, concepts and their connections without an agent running. Local agents perform interpretation and propose new knowledge and relationships. Tags support filtering; typed links explain how nodes relate.
+The GEWU knowledge service contains no reasoning agent. It stores original source artifacts or explicit reference-only records, exposes traceable citations, and lets people navigate problems, approaches, concepts and their connections without an agent running. The custom local agent and other compatible local agents perform interpretation and propose new knowledge and relationships. Tags support filtering; typed links explain how nodes relate.
 
 The initial pilot serves up to five people across 'Dome interactive content' and an 'Interactive Video Platform/Service'. Start with a smaller pilot while retaining the full v1 requirements. Human roles are admin, editor and viewer; editing uses MCP proposals under the read-only web target. Each local agent has its own revocable API key and stable identifier for attribution. Same-agent extraction and support assessment are allowed with recorded assessments and quality sampling. All team members initially read all projects; restricted project access is a later phase.
 

docs/PRD.md

@@ -4,9 +4,9 @@
 
 **Name:** GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Its interpretations vary across traditions. Here it evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse.
 
-Version 0.7 (draft) | 12 Oct 2026 | Status: target-alignment and release-readiness review; owner decisions pending
+Version 0.8 (draft) | 13 Oct 2026 | Status: local workspace-agent and modularity requirements added; remaining policy/operating decisions pending
 
-Current review: [Target alignment and release readiness](reviews/PRD_TARGET_READINESS.md). This revision clarifies acceptance and delivery gates without changing existing P0/P1 priorities. Earlier reviews below retain their historical scope.
+Current design: [Architecture](architecture/ARCHITECTURE.md), [local agent](architecture/LOCAL_AGENT.md) and [modularity protocol](development/MODULARITY_PROTOCOL.md). Revision 0.8 adds the owner-requested custom local workspace agent and replaceable-module requirement. Existing feature priorities remain; the agent pack does not promote P1 synthesis/advanced curation services to P0. The [target alignment and release readiness review](reviews/PRD_TARGET_READINESS.md) describes revision 0.7; earlier reviews retain their historical scope.
 
 Owner decisions confirmed during this review: a smaller pilot precedes full v1; the pilot projects are Dome interactive content and an interactive video platform/service, for up to five people initially. Routine notes may be extracted and support-assessed by the same local agent, with recorded assessment and quality sampling. Human roles are admin, editor and viewer. Each local agent receives its own API key and stable identifier. Project-restricted access follows later; all-team read access remains the initial target. “Editor” is interpreted as MCP proposal permission under the existing read-only web target.
 
@@ -41,7 +41,7 @@ Non-goals (v1)
 - Replacing project management, CRM or code search tools. KB feeds them knowledge but does not manage tasks or deals.
 - A general-purpose chatbot. Agents use KB as a tool, and the UI is for search, navigation and reading.
 - A story-map authoring editor (a canvas for drawing branching story flows) and an embedded in-UI copilot. Agents reach KB through MCP, and story authoring is a separate product.
-- An internal reasoning agent, autonomous research loop or server-hosted curator in the initial system. Ingest, interpretation, semantic linking and synthesis run in external local agents. Server parsing, indexing, retrieval and policy validation are ordinary service functions; embedding computation does not imply an agent inside KB.
+- A reasoning agent embedded in the knowledge service, autonomous server research loop or server-hosted curator in the initial system. Ingest, interpretation, semantic linking and synthesis run in local hosts, including the custom GEWU workspace-agent profile. A separate standalone GEWU reasoning runtime is not required. Server parsing, indexing, retrieval and policy validation are ordinary service functions; embedding computation does not imply an agent inside KB.
 ## Users and use cases
 
 | User | Typical needs | Example |
@@ -265,6 +265,7 @@ Priority: P0 required for v1, P1 important, P2 later.
 | FR-A8 | MCP resources (schema, project registry, node by ID) and prompts (per-project roles, for example an architecture advisor) alongside the tools. | P1 |
 | FR-A9 | Typed tools only. No raw query language (Cypher, SQL) is exposed to agents, and every write goes through a proposal. | P0 |
 | FR-A10 | Expose service/connector diagnostics and compatible tool/schema/skill versions, authenticated capability, selected scope, source-transfer limits, and index status without secrets. Distinguish configured, connected and workflow-verified clients. Installers preserve unrelated client configuration and support a non-symlink fallback. | P0 |
+| FR-A11 | Provide a custom GEWU local workspace-agent pack, following the RESEARCH workspace pattern: one canonical profile, shared protocols, replaceable ingest/query/curate/synthesize skills and coordinating pipeline procedures. Existing supported hosts supply the model/runtime. The pack discovers real MCP capabilities, preserves evidence and permissions, records versioned checkpoints and resumes using durable service receipts. Profile/skill presence alone is not integration acceptance; P1-dependent workflows report unavailable capabilities until implemented. | P0 |
 
 ### 7.5 Compilation and curation
 
@@ -293,10 +294,11 @@ Priority: P0 required for v1, P1 important, P2 later.
 
 1. Source of truth: markdown and YAML files in git.
 2. Derived index: SQLite with full text, vectors and an edges table for v1. It is disposable and rebuildable from canonical files and required source artifacts. Hosted clients use the service rather than opening the database file directly.
-3. KB service: one scoped core with a typed MCP contribution/retrieval interface and a read-only HTTP API for the website. CLI utilities support diagnostics, validation, rebuild and maintenance, not knowledge authoring. Only the MCP proposal path can initiate new knowledge changes; the service validates, applies acceptance policy and commits them.
-4. Skills: judgment procedures (capture, triage, digest, analyze, link, verify, compile, report), kept as one canonical set with a shared concerns to protocol mapping.
+3. KB service: one scoped core with a typed MCP contribution/retrieval interface and a read-only HTTP API for the website. Service maintenance CLI utilities support diagnostics, validation, rebuild and maintenance, not knowledge authoring. A local agent host may have its own CLI, but contributions from it still enter through MCP proposals; the service validates, applies acceptance policy and commits them.
+4. Local agent: a custom workspace profile and canonical skill/pipeline pack, executed by an existing local host. Judgment procedures (capture, triage, digest, analyze, link, verify, compile, report) remain modular, with shared concern-specific protocols and versioned inputs/outputs. There is no additional standalone reasoning runtime in this requirement.
 5. UI: a read-only client for search, navigation and knowledge display. Its credentials and API surface cannot submit, edit or accept knowledge.
 6. Principle: deterministic strictness lives in code (validator, indexer), not in prompts, so different agents and models are held to the same floor.
+7. Modularity: service, agent-pack, connector and UI responsibilities have public contracts and private implementations. Replacements pass shared contract/consumer tests, with explicit version/state migration and rollback. Configuration/composition selects concrete implementations; unrelated modules do not import their internals.
 Reuse from existing work: Jev's contracts, tool registry, owned configuration merging, replay patterns and diagnostics; Winnow's concern-specific protocols, atomic extraction, claim audits and relational synthesis procedures. The [reference review](LOCAL_AGENT_IMPLEMENTATION_REVIEW.md) records limits: Jev's advisory verification/direct writes/character truncation and Winnow's direct vault writes/flattened extraction/prompt-only stages do not satisfy KB's gates. Reimplement those boundaries against KB contracts; no wholesale runtime import is assumed.
 Storage decision (v1). Files in git plus SQLite (full text, vectors and an edges table). A graph server is deferred to limit operational complexity; using one as a derived index would not inherently move the source of truth out of git. Revisit after measured graph-query or scale limits. Cloud document parsers, separate entity-tagging models and heavy entity-matching pipelines are also deferred. Agents get typed tools only, never a raw query language.
 
@@ -310,6 +312,8 @@ One versioned operation catalog declares schemas, handlers, required capabilitie
 
 Provide a canonical, harness-neutral pack with four initial entry points: ingest, query, curate and synthesize. Skills declare concerns and load only relevant protocols (evidence, scope, relationships, proposals and synthesis). They reference service-published schemas and tool versions instead of copying validator rules. Harness setup translates discovery/connection details; it does not duplicate business logic or require lifecycle hooks. Claude requires its own verified client path rather than inheriting a claim of support from another harness.
 
+The owner selected the workspace-agent pattern used by Winnow in SCAR and Praxis in CV. The [GEWU pack](../agents/gewu/README.md) supplies a role, protocols, skill entry points and separate pipeline instructions for an existing local host. Keep the research profile separate from application-development instructions. Model/provider execution belongs to the host; local files do not imply local-only inference. A pipeline document is not a durable scheduler: service run records and receipts, supplemented by private local checkpoints, govern resume and acceptance. Installing a newer skill cannot silently change an active run's pinned instructions.
+
 The local agent reads authoritative project intent and scope through MCP. H1/H2 are explicit task/run context; client cwd and inferred README descriptions are not authority for project selection or H3. External ingestion stages persist source capture, extraction references, triage, bounded note proposals, support assessments and proposed links, then receive validation/acceptance receipts. Resume uses those records instead of conversation history. If lease-based stage ownership is used, an expired worker cannot publish a stale result without revalidation and the current fence.
 
 Atomization optimizes for relevant, reusable knowledge rather than maximum note count. Record source coverage and reasons for skipped/deferred portions; do not silently claim exhaustive processing after a budget limit. Curation keeps incompatible perspectives and conditions separate, uses explicit merge/redirect proposals for duplicates and derives backlinks from stored forward edges. Strong similarity or common sources alone do not establish equivalence.
@@ -317,7 +321,7 @@ Atomization optimizes for relevant, reusable knowledge rather than maximum note
 The capability acceptance matrix records each affected OS/harness pair as PASS, FAIL, BLOCKED, NOT RUN or UNSUPPORTED, with application/connector/service versions and evidence origin. Listing tools or parsing configuration is not the v1 gate: each supported client must perform source transfer, invalid-proposal rejection, eligible automatic acceptance, retry/resume and cited retrieval on the tested deployment. Record local and VPS evidence separately.
 ### Deployment and execution boundary
 
-During development, the service, repository, private archives, index and web app run locally. For team operation they run on the owner’s VPS; ingestion, reasoning and synthesis agents continue to run in local Codex, Claude, Antigravity and OpenCode sessions. The VPS serves retrieval, validates submitted artifacts/proposals, applies policy, commits accepted records and maintains the derived index. Initially KB hosts no reasoning agent or autonomous curator. Semantic support assessments and proposed connections come from external agents; the server checks required records, deterministic evidence rules and policy, without claiming to independently prove semantic truth. Reading and relationship navigation work when no local agent is running; new semantic analysis and synthesis refresh wait for an external agent run.
+During development, the service, repository, private archives, index and web app run locally. For team operation they run on the owner’s VPS; ingestion, reasoning and synthesis agents, including the GEWU profile, continue to run in local Codex, Claude, Antigravity and OpenCode sessions. The VPS serves retrieval, validates submitted artifacts/proposals, applies policy, commits accepted records and maintains the derived index. The KB service hosts no reasoning agent or autonomous curator. Semantic support assessments and proposed connections come from local agents; the server checks required records, deterministic evidence rules and policy, without claiming to independently prove semantic truth. Reading and relationship navigation work when no local agent is running; new semantic analysis and synthesis refresh wait for a local agent run.
 
 Migration to the VPS transfers canonical records, private source artifacts, proposal/run/audit records and configuration, then rebuilds or verifies the index. The local service stops accepting writes before the VPS becomes authoritative; v1 does not promise synchronization between independently writable local and VPS copies. Agent MCP endpoint/credential settings change without changing the contribution contract. Local operation remains supported, but remote VPS access requires connectivity.
 
@@ -372,7 +376,7 @@ The full v1 release gate covers every P0 requirement plus backup/restore of cano
 | --- | --- | --- |
 | M0 Foundations | Node schema, evidence/edge contracts, project registry, validator, proposal/review API and team capability contracts; 20 hand-guided sources across two projects, with the deep-research report as an ingest fixture once supplied (graded as a secondary, AI-synthesized source) | Validator catches seeded errors. Notes validate. Support-review fixtures distinguish quote presence from supported claims. Required pilot sources and expected answers are supplied and labeled. |
 | M1 Service | Index, hybrid search, scoped MCP and read-only HTTP, authentication, durable proposals and automatic acceptance policy | Agents can search, transfer source artifacts and propose from all four harnesses. An eligible proposal is accepted without human action; web writes, unauthorized mutations, scope escape and duplicate acceptance fail. Index-lag recovery is demonstrated. |
-| M2 Ingest | capture, triage, digest, verify, link, run logs, task brief | Cross-agent convergence test passes. |
+| M2 Ingest | capture, triage, digest, verify, link, run logs, task brief; custom local profile, modular skills and coordinating pipelines | Cross-agent convergence test passes. The custom pack completes the source-to-proposal-to-read workflow, records exact versions, and resumes an uncertain operation without duplicate acceptance. Missing P1 capabilities remain explicit. |
 | M3 UI | Read-only project switcher, search, node/source and problem/topic pages, evidence/history, related-node suggestions and staleness | With no agent running, a member opens a problem, explores multiple approaches and their conditions, and follows a citation to an archived source. Suggested matches remain distinguishable from accepted links. Web credentials cannot capture, edit or accept knowledge. |
 | M4 Synthesis | analyze, compile, brief, matrix, timeline, curator report | Briefs produced for each audience. |
 | M5 Multi-project hardening | Promotion to shared, cross-project edge hardening, export and import; acceptance receipts extended to portability workflows | Three projects live on one base without unintended scope mixing. P0 scope enforcement and acceptance receipts already pass at M1. |
@@ -515,3 +519,9 @@ MCP additionally needs typed source-artifact transfer and proposal operations to
 - Added M0 decision gates and a full v1 release gate; retained existing priorities and distinguished confirmed pilot domains from suggested registry IDs.
 - Recorded owner decisions: smaller pilot, two named projects, up to five people, same-agent support with quality sampling, admin/editor/viewer roles and per-agent API keys/identifiers. Project-restricted access remains later.
 - No implementation or runtime acceptance is claimed. Exact pilot client/formats, quality-sampling rules and operating targets remain open.
+
+## Revision notes (0.8)
+
+- Added the owner-requested custom local agent as a workspace profile with skills and pipelines, matching the RESEARCH pattern. Existing local hosts provide execution; the service remains free of an embedded reasoning agent.
+- Added FR-A11 and made replaceable modules a non-functional requirement across service, agent pack, connectors and UI. Public contracts, isolated implementations, replacement tests and migration/rollback are part of acceptance.
+- Added an initial portable instruction pack and linked its design. Structural validation, installation, connection and live workflow acceptance are separate evidence levels; no service or harness pass is implied by these files.

docs/README.md

@@ -1,6 +1,6 @@
 # GEWU architecture and engineering handbook
 
-Started 12 October 2026; revised 13 October 2026. Architecture proposal v0.2; implementation has not started.
+Started 12 October 2026; revised 13 October 2026. Architecture proposal v0.3. The initial local-agent instruction pack exists; service, connector and UI implementation has not started.
 
 **Tagline:** Investigate. Connect. Remember.
 
@@ -15,8 +15,10 @@ GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase comm
 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 the original findings, corrections and limits of verification.
+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.
 
 ## Decision status
 
@@ -24,6 +26,7 @@ The [independent architecture review](reviews/ARCHITECTURE_SENIOR_REVIEW.md) rec
 | --- | --- |
 | 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. |
 
@@ -35,4 +38,4 @@ Start with a disposable local vertical slice: upload an explicitly selected text
 
 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 will be pinned in lockfiles during scaffolding after compatibility checks. There are currently no application manifests, runnable service, browser implementation or deployment tests in this repository. The documents are a reviewable design, not a completion report.
+Runtime versions will be pinned in lockfiles during scaffolding after compatibility checks. The agent pack has an instruction/version manifest, but there are no application dependency manifests, runnable service, browser implementation or deployment tests in this repository. Skill-file validation is separate from installed discovery and live workflow acceptance.

docs/architecture/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # GEWU architecture
 
-Status: proposed baseline v0.2 after [independent review](../reviews/ARCHITECTURE_SENIOR_REVIEW.md). Drafted 12 October, revised 13 October 2026. Product authority: [GOAL](../GOAL.md) and [PRD](../PRD.md). Related: [acceptance contract](ACCEPTANCE_CONTRACT.md).
+Status: proposed baseline v0.3, 13 October 2026. The [independent review](../reviews/ARCHITECTURE_SENIOR_REVIEW.md) covers the v0.2 acceptance foundation; v0.3 adds the owner-required [local agent](LOCAL_AGENT.md) and [module replacement protocol](../development/MODULARITY_PROTOCOL.md). Product authority: [GOAL](../GOAL.md) and [PRD](../PRD.md). Related: [acceptance contract](ACCEPTANCE_CONTRACT.md).
 
 ## Decision
 
@@ -8,6 +8,8 @@ Build a modular Python service and a React reading application in the GEWU code
 
 Local agents reason about sources and submit proposals. The service validates their structure, source locations, permissions and policy eligibility, then records accepted changes. People can search and follow evidence without an agent running. The service contains no reasoning agent, autonomous research loop or general-purpose chat endpoint.
 
+Provide a custom GEWU local agent in the same workspace-profile form as Winnow/Praxis in the RESEARCH folder: a role, shared protocols, modular skills and coordinating pipelines running inside an existing host. The [source pack](../../agents/gewu/README.md) is maintained separately from development instructions. Host/model and transport adaptations can change without duplicating the skill logic; no new standalone reasoning runtime is required.
+
 The starting deployment is one host, one service instance and one canonical writer. This fits the five-person pilot and makes the acceptance boundary inspectable. Capacity remains a measurement gate; five people does not specify simultaneous agent load.
 
 ## Technology choices and reasons
@@ -17,7 +19,8 @@ These are proposed baselines, not installed versions. Use Python 3.12 as the ini
 | Boundary | Choice | Why for GEWU | Alternative and reconsideration trigger |
 | --- | --- | --- | --- |
 | Service | Python, FastAPI, Pydantic, Uvicorn; `uv` for environment/locking | Typed validation and the document-processing ecosystem; consistent with useful AAA/Jev patterns. | A TypeScript-only service saves a language but complicates Python parser integration. Revisit if parser requirements disappear. |
-| Domain core | Plain typed Python modules, explicit dependency injection | The same scope, evidence and proposal rules serve MCP, reads and maintenance. | No generic pipeline/plugin framework until distinct implementations need one. |
+| Domain core | Plain typed Python modules, explicit dependency injection and public ports | The same scope, evidence and proposal rules serve MCP, reads and maintenance; implementations can be replaced behind tested contracts. | No generic plugin framework or process per module. Introduce distribution mechanisms only for a demonstrated extension need. |
+| Custom local agent | Canonical workspace profile, `SKILL.md` modules and versioned pipeline procedures | Matches the owner's RESEARCH workflow; reuses existing hosts/models while keeping GEWU-specific reasoning procedures portable. | A standalone agent engine adds a runtime to maintain and is outside the selected form. |
 | MCP | Official Python MCP SDK; local stdio connector, service Streamable HTTP | One contract across agent harnesses; connector can read selected local files and upload bytes. | Direct remote connections remain a tested option for clients that support the chosen auth profile; a remote path is never a file upload. |
 | Canonical knowledge | UTF-8 Markdown with YAML frontmatter, YAML records, native Git CLI | Reviewable records, exact history, portable exports. | A database as canonical storage conflicts with the present PRD. |
 | Private artifacts | Content-addressed filesystem by SHA-256 | Retain originals without growing Git with PDFs/media. Git records hashes and manifests. | Object storage only after one-host capacity/backup measurements justify it. |
@@ -39,7 +42,8 @@ The exact dependency inventory is a scaffolding deliverable. Model selection and
 flowchart LR
     H[Human reader] --> W[React website]
     W --> R[Read HTTP adapter]
-    A[Local agent harness] --> C[Local stdio MCP connector]
+    PAK[GEWU profile, skills and pipelines] --> A[Existing local agent host]
+    A --> C[Local stdio MCP connector]
     A --> R
     C --> M[Service MCP adapter]
     O[Human owner client] --> M
@@ -59,6 +63,8 @@ flowchart LR
 
 Imports point inward: transport -> application -> domain. Adapters implement storage, Git, clock, parser and embedding interfaces used by application services. Domain code imports neither FastAPI nor MCP nor React. A small lifespan-owned composition root creates services and closes resources. Each application service owns a complete use case; routes translate protocol messages and enforce transport admission.
 
+Every substantial module exposes a versioned public contract and owns its implementation/state. Consumers cannot import its private internals or provider-specific SDK types. The [modularity protocol](../development/MODULARITY_PROTOCOL.md) defines module descriptors, dependency checks, compatible replacement tests and migration/rollback. This applies equally to service components, UI features, skills and pipeline coordinators. Compatible replacement changes composition/configuration rather than unrelated business logic; a breaking replacement declares a consumer migration.
+
 Recommended code layout:
 
 ```text
@@ -69,6 +75,12 @@ src/skb/
   transports/      # MCP, read HTTP, operator/maintenance CLI
   bootstrap/       # configuration and lifespan assembly
 connector/         # local stdio client bridge; uses shared contract package
+agents/gewu/       # actual source pack; installed into a research workspace
+  AGENTS.md        # research role, separate from repository development rules
+  manifest.json    # pack/skill/pipeline versions and verified compatibility
+  protocols/       # evidence, scope and contribution concerns
+  skills/          # kb-ingest, kb-query, kb-curate, kb-synthesize
+  pipelines/       # host-executed coordination and checkpoint procedures
 web/src/
   app/             # routes, providers, shell
   features/        # search, reading, sources, problems, history
@@ -124,7 +136,7 @@ Human browser sessions are expiring HttpOnly, Secure, SameSite cookies. The read
 
 For the initial controlled-team connector, document a GEWU provisioned-key authentication profile over TLS. Do not describe this as generic OAuth interoperability. HTTP MCP authorization has its own specification; supporting arbitrary remote OAuth clients requires a separately implemented and tested authorization-server/resource-server profile. The local stdio connector avoids assuming all four harnesses support the same remote authentication flow.
 
-Protected changes use the human-authenticated owner MCP client and a digest-bound decision described in the contract. The proposed owner profile uses a short-lived opaque session obtained by password and TOTP reauthentication in a separate human terminal; it is an GEWU-controlled client profile, not a claim of generic OAuth support. Production separates the human owner credential from the agent's OS account/credential store. Owner-level unrestricted filesystem agents cannot be claimed to be isolated by prompt instructions.
+Protected changes use the human-authenticated owner MCP client and a digest-bound decision described in the contract. The proposed owner profile uses a short-lived opaque session obtained by password and TOTP reauthentication in a separate human terminal; it is a GEWU-controlled client profile, not a claim of generic OAuth support. Production separates the human owner credential from the agent's OS account/credential store. Owner-level unrestricted filesystem agents cannot be claimed to be isolated by prompt instructions.
 
 Local operation uses the same core and directory layout as the VPS. Development may run on the user's account with disposable data; enforced pilot/team operation uses a separate service identity. VPS publication requires an independent restore test, HTTPS, private volumes and client workflow evidence. Moving authority to the VPS freezes local writes first; there is no independently writable local replica synchronization in v1.
 
@@ -135,6 +147,7 @@ Local operation uses the same core and directory layout as the VPS. Development
 | M0 contract slice | Schemas, state machine, safe file records, scope/policy fixtures; pin dependencies | Seeded invalid evidence/authority rejected; public schemas generated; decisions below settled for affected boundary. |
 | Pilot end-to-end | Proposed starting point: Windows/Codex, text/Markdown, two projects plus shared, lexical search first | Upload -> proposal -> automatic acceptance -> committed read -> citation; crash/replay tests; read-only browser. Client/format choice remains recommended. |
 | Full P0 service | Hybrid index, all required input types, four harnesses, portability and protected decisions | Per-client transfer/rejection/acceptance/retry/retrieval receipts; no scope or authority bypass. |
+| Custom agent and module gates | Install GEWU profile/skills into an isolated research workspace; enforce dependency boundaries and pinned module/skill versions | Native host ingestion/query and interrupted-run recovery; compatible module swap passes contract/consumer tests. Instruction-pack presence alone cannot close this gate. |
 | Team release | VPS migration, backup/restore, quality sampling, capacity/security acceptance | All selected PRD P0 gates plus measured retrieval, evidence and human reading tasks. |
 | P1 follow-up | Rich comparisons, graph canvas, promotion/import/export and synthesis/curation | Explicitly selected requirements and their own acceptance evidence. |
 

docs/architecture/LOCAL_AGENT.md

@@ -66,6 +66,8 @@ For a connected run, service run identity, proposal revisions and acceptance rec
 
 Pin the installed pack snapshot for an active run. If that version is unavailable after an upgrade, pause with a compatibility finding or explicitly start a successor run. Reuse previous outputs only when their hashes, evidence bindings and new stage contracts still hold; revalidate downstream stages after changes. Install/version manifests alone cannot enforce this in arbitrary hosts; native workflow tests must demonstrate it.
 
+The pack manifest supplies per-module implementation and instruction-contract versions, dependencies, compatible checkpoint contracts and file hashes for the profile, shared protocols, skills and pipelines. Run checkpoints retain the snapshot digest and resolved module IDs/contracts/hashes. Its service-capability requirements remain explicitly unbound until wire schemas exist; empty capability arrays are not a declaration of compatibility. The draft checkpoint fields and snapshot calculation are specified in the pack README.
+
 A pipeline has a bounded work/correction budget, explicit coverage and a resumable stop. Two unchanged validation failures are a default stop for diagnosis, not permission to relax checks. Network uncertainty triggers status lookup, not a fresh proposal identity. Protected decisions leave the agent workflow for the separate human owner client. No continuous watcher, automatic external messaging or unbounded research loop is introduced.
 
 ## Acceptance and sequencing

docs/development/AGENT_SECURITY_PROTOCOL.md

@@ -1,11 +1,15 @@
 # Agent contribution and security protocol
 
-Status: proposed v0.1, 12 October 2026. Contracts: [architecture](../architecture/ARCHITECTURE.md) and [acceptance](../architecture/ACCEPTANCE_CONTRACT.md).
+Status: proposed v0.2, revised 13 October 2026. Contracts: [architecture](../architecture/ARCHITECTURE.md), [local agent](../architecture/LOCAL_AGENT.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.
 
+The [GEWU source pack](../../agents/gewu/README.md) follows the owner's RESEARCH workspace pattern: profile, shared protocols, modular skills and coordinating pipeline instructions. The selected host supplies the model/runtime. Its manifest currently declares no verified service compatibility. Install into a dedicated research workspace and preserve existing profiles; source-pack creation is not host installation or a successful connection. Local host execution does not establish local-only inference.
+
+Pin pack/skill/pipeline content for active runs, and record version/hash bindings with checkpoints. A profile cannot enforce isolation through prose; service capabilities and deployment permissions remain authoritative. A pipeline Markdown file cannot guarantee durable scheduling. Resume uses service status/receipts and retained output artifacts; missing compatibility or unavailable old instructions must be reported explicitly.
+
 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.

docs/development/DEVELOPMENT_PROTOCOL.md

@@ -20,7 +20,7 @@ Every implementation task names its owning module, public boundary and affected
 | 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. |
+| Local agent profile and pipelines | Own research-role routing, stage procedures, budgets and resumable checkpoint guidance. The existing host supplies model/tool execution. Use public MCP contracts; never depend on service 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.
 

docs/development/MODULARITY_PROTOCOL.md

@@ -4,7 +4,7 @@
 
 ## 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.
+Use a modular monolith for the service and a separate local-agent instruction pack executed by an existing host. 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.
 
@@ -29,8 +29,8 @@ Compatibility is behavioral: valid inputs, errors, cancellation, ordering, idemp
 | 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. |
+| Agent host/model adapter | Profile discovery, model capabilities, tool access and execution metadata | Change configured host/model without baking provider syntax into shared skills. The host owns its provider SDK. |
+| Agent pipeline coordinator | Stage inputs/outputs, work budget, checkpoints and outcomes | Replace coordinating instructions while preserving skill contracts and resume obligations. The initial coordinator is host-executed Markdown, not a standalone engine. |
 | 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. |
@@ -40,7 +40,7 @@ Compatibility is behavioral: valid inputs, errors, cancellation, ordering, idemp
 
 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.
+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. Local-agent helper/connector code 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.
 

docs/reviews/LOCAL_AGENT_MODULARITY_REVIEW.md

@@ -0,0 +1,27 @@
+# Local agent and modularity review
+
+13 October 2026. This record covers the local-agent and modularity additions after the architecture v0.2 review. It does not establish runtime acceptance.
+
+## Requirement and reference findings
+
+The owner requested a custom local agent with skills and pipelines, similar to their RESEARCH agents, and required replaceable modules throughout development. Inspection of Winnow in SCAR and Praxis in CV confirmed the relevant pattern: a workspace role, shared protocols, reusable skills and coordinating procedures executed by an existing host. SCAR's `.agents` points to `.opencode`; CV owns `.agents` directly. Their runtime workflows were not retested, and no reference-workspace instructions were activated for this task.
+
+The [local-agent decision](../architecture/LOCAL_AGENT.md) adopts this form. The [source pack](../../agents/gewu/README.md) contains a profile, readiness/version manifest, evidence/scope/contribution protocols, four skills and four pipeline procedures. It introduces no standalone reasoning engine. Service compatibility and native host acceptance remain unverified. Files are supplied in the repository; no user-global configuration or installed research workspace was changed.
+
+## Design changes
+
+The [modularity protocol](../development/MODULARITY_PROTOCOL.md) makes public contracts, owned state, dependency direction, versioning, migration and replacement evidence explicit. It covers backend adapters, agent instructions, connector and frontend. A modular monolith is the service default; process separation is a deployment decision. Replacement must preserve behavioral and security invariants or declare an explicit contract migration.
+
+The GOAL, PRD, architecture, development and security documents now distinguish the custom local profile from reasoning inside the knowledge service. The profile supplies ingest, query, curate and synthesize procedures; existing P1 synthesis and advanced-curation service priorities remain unchanged. Checkpoints preserve versions and outputs, while actual service receipts remain authoritative for acceptance. Markdown instructions do not establish durable execution, native skill discovery or safe retry behavior by themselves.
+
+## Verification
+
+All four skills pass the skill-creator structural validator. That check covers frontmatter and basic skill structure; it does not test semantic quality, tool connectivity or host behavior. A separate manifest check passed for all 12 referenced paths, unique skill IDs, matching skill names and pipeline versions, and explicit unverified compatibility status.
+
+Across 30 Markdown files, local links and heading anchors resolve; fence and trailing-whitespace checks found no issues. The prose scan checked 76 patterns across the 16 new pack/design/review files and found no matches. `git diff --check` passed. These are static checks; they establish neither execution nor replacement behavior.
+
+The bounded independent review found no blocker and one major gap: the pack's own profile and protocols lacked versioned replacement contracts. The repair adds descriptors for every instruction module and the checkpoint guide, explicit dependencies, checkpoint compatibility, per-file hashes and a snapshot digest. Contribution instructions require those IDs and digests in run records. Service capability binding remains explicitly pending. The descriptor/hash checks establish internal consistency; native resumption and upgrade compatibility still need execution tests.
+
+The reviewer confirmed that finding closed at design level with no residual concrete defect. Final checks cover 13 module descriptors and hashes, their internal dependencies, the snapshot digest, 129 local links and five anchors. Markdown hashes normalize UTF-8/BOM and line endings as specified in the pack guide so checkout conversion does not change instruction identity. Hashes establish content identity, not trust or execution safety.
+
+Runtime acceptance remains pending: install into a disposable workspace after the service contracts exist, verify discovery and read-only retrieval, then complete ingestion, invalid-evidence rejection, uncertain-result recovery and resumption with pinned versions. Full-v1 host claims require the declared client matrix. Module substitution, migration and rollback tests must accompany implementation.