GEWU/docs/PRD.md

GEWU — Multi-Project Knowledge Base for Humans and AI Agents

Tagline: Investigate. Connect. Remember.

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

Current review: Target alignment and release readiness. This revision clarifies acceptance and delivery gates without changing existing P0/P1 priorities. Earlier reviews below 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.

Review report: PRD_REVIEW.md. Target confirmed on 12 Oct 2026: a shared team plus agents; every team member may read every project in v1. Confirmed workflow: local development first, deployment to the owner’s VPS later; a read-only web app; knowledge contributions exclusively through MCP from local Codex, Claude, Antigravity (agy) and OpenCode agents. Eligible proposals may be accepted automatically; exact eligibility rules remain to be finalized.

Implementation-reference review: Jev and SCAR/Winnow lessons, with isolated probe evidence. Reuse recommendations are bounded by the reviewed working trees; neither project is a required runtime dependency.

Summary

GEWU is a local-first, git-based knowledge base that turns collected material (web pages, papers, reviews, NotebookLM exports, talks, internal notes) into evidence-backed, linked, reusable knowledge. It serves two kinds of readers equally: people (through a web UI) and AI agents (through MCP and an HTTP API). One installation hosts many projects, each identified by a project_id (for example interactive-video, dome-performance, agentic-design). Projects keep their own goals, taxonomies and curated notes, and can draw on a shared library of sources, entities and concepts. The core idea is three layers: immutable sources, atomic notes extracted from them with evidence, and compiled syntheses (briefs, market overviews, timelines, comparison tables) built from the notes. Agents write only by submitting proposals that pass a validator.

The v1 delivery target is a team-operated KB service with a shared web UI and agent access. One authoritative repository and service coordinate accepted changes. Team members may read all projects; project scope controls relevance, not confidentiality. Authentication and permissions to propose, evaluate, and manage project intent are required. The service validates and automatically accepts eligible proposals under the project policy; routine knowledge does not require human approval. Development runs locally first, then the same service and canonical data move to the owner’s VPS. Local agent harnesses connect to that service through MCP. The web app only searches, navigates and displays knowledge; it has no capture, edit, review-decision or acceptance controls.

Problem and opportunity

• Research for a project is scattered across browser tabs, PDFs, NotebookLM notebooks and chat histories, and is hard to reuse by a different person, agent or project.
• AI agents working on development, writing, presentations, budgets or marketing plans start each session without the project's accumulated knowledge, or get it as unverified summaries.
• Existing note tools store text but do not enforce provenance, evidence strength, freshness or typed relationships, so market numbers go stale, contradictions go unnoticed and claims lose their sources.
• Knowledge that applies to several projects (for example agentic design patterns used in both an interactive video tool and a dome show pipeline) is duplicated or lost.

Goals and non-goals

Goals

1. One knowledge base, many projects. Every node belongs to exactly one project or to the shared library, and queries can be scoped accordingly.
2. Evidence-backed knowledge. Every claim traces to a source and a quote location that a validator can check.
3. Dual-audience access. Humans browse, learn and search in a UI. Agents retrieve cited, budgeted, structured answers through MCP and API.
4. Agent-agnostic. Works from OpenCode, Claude, Codex and Antigravity through shared files, skills and MCP, with no logic locked inside one tool.
5. Goal-aware ingestion. A local agent pipeline digests new material against the project's goal (three horizons) and proposes notes, links and insights.
6. Multi-audience value. The same nodes serve developers, product managers, project managers and sales through facets and saved lenses.
7. Trustworthy over time. Dated claims, staleness tracking, contradiction links and a full audit trail. Non-goals (v1)

• Real-time collaborative editing of the same document. Shared search and reading are in scope; MCP proposal processing and accepted changes are serialized through the service into git.
• Hosting copyrighted source texts for redistribution. KB stores notes, short quotes and links, and keeps archived copies private.
• 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.

Users and use cases

User	Typical needs	Example
Developer	Problems and proven techniques, architecture precedents, case studies	How do interactive movies avoid combinatorial explosion of branches?
Product manager	Market shape, competitors, user problems, feature precedents, comparisons	Compare how three titles handled player choice pacing.
Project manager	History, timelines, cost and schedule datapoints, risks	Timeline of interactive film production tooling for a kickoff deck.
Sales	Market overview, positioning, proof points, objections, as-of numbers	Current market size claims and who made them.
Ingest agent	Digest a source against the project goal and propose notes	Process a new paper into proposals with evidence and edges.
Consumer agent	Retrieve cited knowledge during coding, writing, budgeting, marketing	Fetch a brief for a presentation with token budget 2,000.
Curator agent	Find stale, duplicate, contradictory or orphan nodes	Weekly report of stale market datapoints.
Project owner	Define intent, set autonomy policy and resolve exceptions through local agent workflows	Authorize a goal change or resolve an ambiguous knowledge proposal without approving every note.

Multi-project model

This section defines how one database serves many projects.

5.1 Project registry

Each project has a registry entry projects/<project_id>/project.md with frontmatter:

• project_id: lowercase slug, unique, immutable (for example interactive-video, dome-performance, agentic-design).
• title, description, status (active, paused, archived), owners.
• north_star: the project's main goal (Horizon 3), human-owned. Agents may propose edits through review, never change it directly.
• key_questions, watch_list (competitors, technologies, titles, people), out_of_scope.
• audiences: which audiences the project cares about.
• taxonomy_extensions: project-specific domain tags and node subtypes added to the core vocabulary.
• autonomy_policy: per node/change type, suggest or auto-merge-safe, with required evidence/support checks and exception rules. research-on-gap is a separate research trigger, not an acceptance permission.
• default_includes: other projects or shared whose nodes appear in this project's searches by default. Horizons 1 (current request) and 2 (session objective) are not stored in the registry. The agent derives them per task and records them in the run log.

5.2 Scope of every node

Every node has project_id, which is either a registered project or the reserved value shared.

Scope	What lives there	Rule
Project	Notes, syntheses, project-specific cases and datapoints	Owned by one project. Reviewed against that project's lens.
Shared	Sources, entities (companies, people, tools, titles), general concepts, cross-domain techniques	Deduplicated globally. Any project can reference them.

Rules:

1. Sources and entities default to shared, so one paper or company is stored once and referenced by many projects.
2. Notes default to the project that triggered ingestion. A note can be promoted to shared when it is useful beyond the project, through a review action that records who promoted it and why.
3. Cross-project links are allowed and explicit. A project node can link to a shared node or to a node in another project with a typed edge. The edge records the project pair, and the UI and API mark it as cross-project.
4. Relevance is per project. A node has lens_fit keyed by project: a note about agentic design patterns can carry a high score for agentic-design and a medium score for interactive-video, without being copied.
5. Every content operation supplies an explicit project/scope context. If includes are omitted, the server resolves that project's default_includes plus shared. Other scopes are opt-in (projects=[...] or all). Responses report the resolved scope and origin of each returned node; no transport silently infers a project from an earlier session.
6. Scope applies to direct ID lookups, graph traversal, comparisons, citations, syntheses and MCP resources as well as search. An out-of-scope ID cannot expand a request's scope. Cross-project targets outside the resolved scope are marked as omitted, with an explicit action to widen scope.

5.3 Identity and layout

• Node IDs are globally unique: <project_id>: for project nodes and shared: for shared nodes. IDs remain stable on title and file renames. Promotion to shared changes the namespace through one reviewed migration that creates a permanent old-ID redirect, updates references, and preserves origin and history; IDs are never reused. Redirect resolution remains subject to the destination scope.
• Repository layout (single repo, namespaced):

kb/
  shared/{sources,entities,notes,synthesis}/
  projects/<project_id>/{project.md,notes,synthesis,staging,runs,lens/}
  schema/ protocols/ skills/ src/ docs/

• A separate repo per project is not used in v1, because shared sources and cross-project links would need duplication or submodules. The repo can still be split later because every node carries its project_id.

5.4 Isolation and export

• v1 serves one trusted team and its agents. All authenticated team members may read every project, but every content API call still supplies scope and the validator rejects unknown project_id values. Logical project separation is not a confidentiality boundary.
• All network interfaces authenticate callers. The service authorizes reader, proposer, reviewer and project-owner capabilities; agent credentials are limited to reading and proposing. Changes to human-owned intent and autonomy policy require attributable project-owner authorization submitted through the MCP workflow; agents cannot self-authorize those changes. The owner-authorization mechanism is an M0 contract decision and must not rely on an agent merely claiming that approval occurred. Audit records distinguish the authenticated caller from a self-reported agent/model identity.
• Per-project export (nodes, linked shared nodes, and an index) must be possible so a project can be handed over or archived.
• Per-project confidentiality and granular project ACLs remain P2 under the confirmed all-team-read target. Team authentication and mutation permissions are P0 and cannot be deferred with those ACLs.

Acceptance authority follows the records changed, not just the project that initiated a run. A project policy cannot authorize mutations to shared records or another project's records. Shared has explicitly assigned owners and its own acceptance policy. M0 must define whether bundles spanning policy domains are accepted atomically under every affected policy or submitted as ordered dependent proposals. Partial application must never be reported as complete acceptance; missing policy or authorization holds the affected change. Read scope and lens relevance grant no mutation authority.

Initial human roles and agent identity:

Principal	Initial permissions	Boundary
Viewer	Read all projects through the website and permitted read tools	Cannot propose or decide changes.
Editor	Viewer permissions plus knowledge proposals and corrections through MCP	Cannot change protected intent/policy or administer credentials without a separate owner/admin grant. The website remains read-only.
Admin	Manage members, role assignments, agent credentials and project/shared ownership; bootstrap the first owner	Protected knowledge/intent changes still use validated, attributable MCP workflows. Credential administration is a control-plane operation, not a knowledge-authoring bypass.
Local agent	Read and propose within capabilities assigned to its credential	Has a unique stable agent_id and its own revocable API key; cannot inherit admin powers from the human running its harness.

Project-owner authority is an explicit grant, separate from the editor role. M0 specifies how admin and owner grants interact and how humans authenticate protected decisions without disclosing their credentials to an agent. Agent credentials bind server-side to agent_id, responsible human, capabilities and a non-secret key identifier. Rotation preserves agent_id; revocation prevents subsequent requests and acceptance evaluation rechecks current authorization. Audit records retain agent_id, key identifier, responsible human, proposal/run IDs, policy and resulting revisions; self-reported model/harness labels cannot override that identity. Never store raw keys in git, logs or node metadata. Key issuance, rotation, revocation and attribution are P0 acceptance cases. Simultaneous agent load remains to be sized separately from the five-person pilot.

Content model

6.1 Layers

1. Source (immutable): archived snapshot or reference, hash, bibliographic and reliability metadata. Never edited by agents.
2. Note (atomic): one finding, claim, problem, technique, case, datapoint or event, with evidence quote and location.
3. Synthesis (compiled): topic pages, briefs, market overviews, timelines and comparisons assembled from accepted notes. A compiled brief is a cited summary across multiple notes, such as a comparison of branching techniques. Local agents can create or refresh a saved synthesis and submit it through MCP; once accepted, the website displays it like other knowledge. Whether KB also needs a dedicated brief retrieval/assembly tool remains a P1 scope decision; a model running on the VPS or generation inside the website is not required.

6.2 Node types

Source, Finding/Claim, Problem, Technique/Solution, Case, Entity, Datapoint, Event, Concept, Synthesis. Projects may add subtypes through taxonomy_extensions. Project subtype packs. A project adds subtypes and fields through its registry, and the same validator checks them. The interactive-video pack starts with these four, taken from the deep-research report:

Subtype	Based on	Key fields
Production case	Case	release year, studio, delivery medium (FMV, real-time 3D, streaming player, theatrical), budget, reported revenue, units sold, total and average playthrough runtime, shooting ratio, decision points, endings
Narrative mechanism	Technique	paradigm (branch-and-bottleneck, state variable, storylet, database cinema, foldback), complexity class, authoring overhead, agency profile
Technical constraint	Problem	domain (buffering, state storage, bandwidth, platform parity), severity 1-5, mitigation
Market metric	Datapoint	metric type (market size, conversion, ticket premium, completion drop-off), demographic, value, unit, sample size, reporting year

Other projects define their own packs. All subtype fields follow the evidence rules in 6.3.

6.3 Metadata

All nodes: id, project_id, type, title, summary (1-2 sentences for agents to scan), created, updated, review_state (draft, reviewed), lifecycle (active, superseded), confidence (low, medium, high), tags, schema_version. Freshness (current, stale, unknown) is derived at read time from the recorded dates and dependencies. Facets: audience (dev, product, pm, sales), domain (project-extensible core set: tech, design, market, history, legal, production, marketing), use_for (presentation, budget, comparison, architecture decision, pitch). Lens fit: lens_fit: {<project_id>: {score, horizon, key_question, reason}}. Provenance: derived_from: [{source, revision, quote, loc}], run_id of the agent run that proposed it, agent and model identity. This evidence list is canonical; displayed evidence quotes and provenance edges are derived from it rather than separately editable copies. Source-specific: URL, author, publisher, publication date, access date, source type (paper, review, press, vendor, internal), reliability grade, archive path, license note. Claims and datapoints: evidence_type (measured, reported, opinion, vendor marketing), as_of, stale_after, and claim_support (pending, supported, unsupported) with a review rationale. Each assertion or factual field maps to one or more canonical evidence entries. Source reliability, quote validity, claim support and confidence are separate attributes; no one implies the others. Datapoint values: value, unit, sample_size, reporting_year and demographic (where relevant) are separate fields from the quote, so numbers can be compared and charted. Entities: aliases (alternate names) and merged_from (IDs merged into this node, so a merge can be undone).

6.3.1 Evidence and source revisions

• A source has a stable identity and immutable captured revisions, each with a content hash, capture time, original artifact and normalized extraction when available. A URL identifies a source candidate, not an immutable revision: changed content at the same URL creates a new revision. Fetch failure never replaces an existing capture.
• Evidence locators identify the exact revision and extraction version, with format-specific locations (PDF page and text span; web/text block and span; transcript timestamp and span). Quote checks use documented normalization and verify the stated location, not merely the presence of the quote somewhere in the document. OCR and parser limitations are recorded.
• Quote validation proves that text occurs at a location. Claim-support review separately assesses whether that text supports the assertion, number, unit, population, date and qualifiers. A passing quote check alone must never label a claim verified.
• Support assessments are structured records from external agents or an authorized human: claim ID, source/extraction revision, assessor/run, method, status and rationale. Missing references, unavailable assessment or a failed check never become a successful verification. The server checks required assessment records and policy without claiming to independently establish semantic truth. Optional relevance/index features may degrade; acceptance evidence requirements may not.
• Unavailable archives or failed extraction produce an explicit unverifiable state. Such sources and draft proposals may be retained, but their claims cannot enter the accepted evidence-backed corpus until checkable evidence and support review are available. This preserves the 100% merged-claim citation target.
• An AI-synthesized report is evidence of what that report says. Its underlying factual claims require checked primary evidence before being presented as primary-source-backed. A reference list alone does not establish that evidence.
• Interpretations are explicitly labeled and cite their supporting notes; they are never presented as source statements. Factual assertions embedded in interpretations or syntheses follow the same evidence rules as notes.

6.3.2 Lifecycle and freshness

Review state, freshness and lifecycle are separate dimensions in the schema; a reviewed node may also be stale. Source immutability applies to captured content; corrected bibliographic metadata is a versioned, reviewed change.

Datapoints require as_of and a stale_after deadline with a recorded policy or rationale. The service evaluates freshness at read time, even if the curator has not run. Syntheses record input node revisions and compilation time; changed, stale or superseded inputs trigger a visible warning until reviewed regeneration. These warnings survive every output format and budget reduction.

Displaying accepted syntheses and their dependency warnings belongs to the P0 read contract whenever such nodes exist. Automated discovery of refresh work and the dedicated compilation/brief workflow remain P1 (FR-C1/FR-A4). Deferring refresh tooling cannot hide known dependency warnings. Read-time freshness uses the current service time and canonical dependency revisions even when the search index lags.

6.3.3 Source intake and later reference

Each source page distinguishes the source identity, immutable revisions and attached artifacts. It displays title, authors/publisher when known, original URL if present, capture time, hash, archive availability, extraction status and notes that cite that source. References target a specific revision and location, not the latest bytes at a URL.

Input through MCP	What KB retains	Later reference
Local original file	Original bytes in private artifact storage, hash, file/MIME metadata and a source-revision record; extracted text with parser/version and location mapping where supported	Authenticated original download/preview and exact citation location; previews depend on supported format
Public URL with capture requested	Original URL, fetch/final URL, capture time and immutable captured content where fetching succeeds	Both live original link and captured revision; changed content produces a new revision
URL registered without a usable capture	URL and bibliographic metadata, with explicit reference-only or capture-failed state	A useful bookmark/source record, but not checkable evidence for accepted factual claims until evidence is archived
Locally obtained restricted/dynamic page, transcript or export	Agent-submitted capture plus original URL, capture method and provenance; original and derived artifacts distinguished	Cite the supplied artifact accurately; a transcript or export must not be labeled the original recording/page

Source registration is separate from knowledge extraction. Staging an upload does not accept its metadata or claims; completing the artifact and source proposal returns a stable source ID, revision ID and acceptance/validation status. Multiple nodes and projects reuse that source without duplicating its bytes. Interrupted uploads cannot become citable revisions. Hash dedupe does not discard distinct provenance records.

Extraction preserves page/block/span mapping to the captured revision and records parser version, empty/scanned pages and unsupported content explicitly. Converting a PDF to one text string is not sufficient citation evidence. Keep native source versions (for example an arXiv revision) distinct from title and source identity. Metadata/abstract retrieval alone is not original-file capture. Agent-generated contents tables and reading guides remain separate from immutable originals.

Store source metadata, artifact manifests, hashes and evidence references in git; store large original binaries in private content-addressed artifact storage alongside the service, included in backup/restore. A manifest reference alone is not an archived original. Reading/downloading an existing artifact from the website is within the read-only boundary. Active source content is not executed inside the application; unavailable previews still offer the original download and available extracted text.

MCP implementation boundary. KB defines application tools for source registration and artifact transfer. MCP provides schema-defined tool calls and resource retrieval; merely connecting an MCP client or passing a local path does not upload a file. Recommended implementation: a small local MCP connector offers a file-path tool, reads the explicitly selected local file, and transfers its bytes to the authoritative KB using authenticated, bounded upload-session/chunk/finalize tools. The connector is ordinary transport code, not an agent. File bytes stay outside model-visible tool responses. Remote-only clients can register URLs or use supported artifact-transfer tooling; the VPS cannot dereference a path on the user's computer. This proposed connector/transfer design must be tested in all four harnesses; tool schemas, maximum sizes and resumption rules are M0 deliverables.

Protocol references: MCP tools and MCP resources. Upload tools described here are KB-specific, not protocol-standard file upload methods.

6.4 Typed edges

solves, causes, supports, contradicts, instance_of, part_of, precedes, supersedes, compared_with, derived_from, plus applies_to (node to project) for cross-project relevance. Edges live in frontmatter and are validated: the target must exist and the edge type must be allowed between the two node types. Projects add extension edges in their registry, each with allowed source and target types. The interactive-video pack adds implements (case to mechanism), introduces (mechanism to constraint, a project-level form of causes), mitigates (technique to constraint), has_metric (case to datapoint) and incurs_cost (problem to datapoint). documented_in is the core derived_from edge. The core set stays small so other projects are not forced to carry these.

Add core addresses (technique to problem) for a relevant or partial approach without asserting that it solves the problem completely. A solves edge requires support for its stated applicability. Edges that make substantive claims carry evidence references or an explicitly labeled interpretive rationale, proposer/run identity and relevant conditions. Conditions belong to the technique-problem relationship when they vary by use case. Tags or similarity scores cannot establish a solves, supports or contradicts relation.

6.5 Grouping and navigating knowledge

Use several complementary forms of organization:

Mechanism	Purpose	Example
Problem node	A stable question/problem page gathering incoming addresses/solves links, cases and evidence	How can we control branch explosion?
Technique/Solution node	A reusable method linked to each applicable problem, with conditions and limitations	State-based branching linked to several problems, without copying the technique
Concept/topic node	A browseable subject with explicit part_of membership, under documented allowed edge types	Numerical optimization groups methods and problems
Tags and facets	Broad many-to-many filtering by subject, audience, use or domain	numerical-methods, real-time, dev
Synthesis node	An agent-authored, cited reading guide or comparison over selected nodes	Overview of approaches to one problem
Similarity suggestions	Discovery candidates computed from the index, with the reason shown	Similar text, overlapping tags or a shared neighbor

Problem pages are computed from accepted nodes/edges; they do not require a prewritten synthesis or an internal agent. Show approaches with applicability, assumptions, limitations, supporting references and case studies. Mathematical/technical methods may record input requirements, guarantees versus heuristics, accuracy, computational cost and known failure conditions when supported. Unknown values remain unknown. Multiple solutions remain distinct; shared tags or a common problem do not establish equivalence or a universal ranking.

Every node page separates linked knowledge (accepted typed relationships, including incoming links) from suggested related nodes (derived similarity candidates). Each related item states why it appears. The server computes inverse navigation from stored edges rather than requiring duplicate reverse-edge writes. Similarity never silently becomes an accepted graph edge; a local agent can propose such a connection through MCP with its rationale/evidence. All lists honor the resolved project scope and disclose omitted cross-project targets. When no accepted approaches exist, show that gap; suggestions must not be labeled proven solutions.

Example navigation: a problem page lists Technique A and Technique B through their addresses/solves edges; each technique links to its case studies and cited source revisions. A separate related section may suggest another problem with overlapping concepts. Clicking a tag filters the collection; clicking a typed relation explains the specific connection. These read-only pages are P0; an interactive graph canvas and rich comparison matrix remain P1.

Functional requirements

Priority: P0 required for v1, P1 important, P2 later.

7.1 Project management

ID	Requirement	Pri
FR-P1	Create, archive and list projects from a registry entry, and the validator rejects nodes with unregistered project_id.	P0
FR-P2	Every read and write API takes a project scope, with the documented default scope.	P0
FR-P3	Shared library with global dedupe of sources and entities.	P0
FR-P4	Promote a note to shared, and mark links as cross-project in API and UI.	P1
FR-P5	Per-project lens (north-star, key questions, watch list) read by ingest and curation.	P0
FR-P6	Per-project export and import.	P1
FR-P7	Per-project access control.	P2
FR-P8	Authenticate team members with admin/editor/viewer roles and explicit project-owner grants; issue each local agent its own API key and stable agent_id. Enforce capabilities, rotation/revocation and human-owned intent; record the actual caller and credential identifier on proposals and decisions without recording secrets. All authenticated team members may read all projects initially; project-restricted access remains P2.	P0

7.2 Ingestion

ID	Requirement	Pri
FR-I1	Local agents capture URL, PDF, file, pasted text and NotebookLM exports and submit source artifacts and proposals through typed MCP tools. A local inbox may be an agent input but never an alternate server write path. MCP transfers required artifact bytes and hashes to service-managed storage and returns source/revision IDs; local absolute paths alone cannot identify files on the VPS.	P0
FR-I2	Archive immutable source revisions, hash and normalize metadata, dedupe identical captures globally, and use URL matches to find prior source identities without discarding changed revisions.	P0
FR-I3	Triage against the project lens: relevant or skip, with score and reason.	P0
FR-I4	Digest extracts schema-valid notes with quote and location for every claim.	P0
FR-I5	Analyze writes learnings and points of interest per horizon, labeled as the agent's interpretation and kept separate from source claims.	P1
FR-I6	Link resolves entities to a canonical name plus aliases (name normalization and embedding similarity find candidates, the agent judges borderline matches), logs every merge so it can be undone, proposes typed edges and flags contradictions.	P0
FR-I7	Verify checks quotes at their locations against the exact source revision and records claim-support assessment separately from source reliability and confidence. Unverifiable or unsupported claims remain outside the accepted evidence-backed corpus.	P0
FR-I8	All writes go to staging/ as proposals, with a run log.	P0
FR-I9	Tag each source with the projects it was ingested for, so one source can serve several projects.	P0
FR-I10	Task brief: agent derives H1 and H2 for each run and stores them in the run record.	P1
FR-I11	Durable manifests for external-agent runs: run/project/source revision, stage, skill/schema versions, input/output hashes, proposal IDs and last receipt. Bounded batches record coverage, skips and deferred work. An interrupted local agent can inspect and resume verified stages through MCP without recreating accepted nodes. KB records progress; it does not execute a reasoning agent.	P0

7.3 Validation and review

ID	Requirement	Pri
FR-V1	kb validate checks schema, required fields, link resolution, edge-type rules, project scope and each quote at its stated location in the archived revision. Acceptance also requires the applicable support-review decision and authorized reviewer/policy. Failed proposals may persist in staging but cannot enter the accepted corpus.	P0
FR-V2	MCP proposal/status operations let local agents inspect validation findings, submit corrected revisions, provide support assessments and propose duplicate merges. Eligible proposals auto-accept through service policy; exceptions are handled in the local agent conversation. Record decisions and policy identity. No web review inbox or mutation controls.	P0
FR-V3	P0 policy-controlled automatic acceptance per project and change type. Valid eligible proposals proceed without human approval; failed checks return actionable findings for agent correction, while ambiguous or protected changes await the applicable decision. Policies cannot waive schema, scope or evidence requirements. Quality audits and graduated tuning can follow as P1.	P0
FR-V4	Contradictions are linked, never overwritten. Superseded nodes stay with superseded_by.	P0
FR-V5	Proposal lifecycle is staged, validating, accepted or rejected; needs-review is an exception state rather than a mandatory step. Validation-failed and conflict outcomes allow correction. Each proposal carries an ID, base revision, author, change bundle, evidence results and decision history. Acceptance revalidates against current state, serializes repository writes, and returns a durable receipt with commit and index status. Retrying a proposal ID cannot create a second acceptance. Any proposed-content or support-assessment edits invalidate prior validation.	P0

7.4 Retrieval and agent interface

ID	Requirement	Pri
FR-A1	MCP exposes P0 tools search, get_node, neighbors, list_projects, source-artifact submission, proposal submission/status/revision and flag_stale. The website HTTP API exposes read operations only; it has no knowledge mutation endpoints. MCP may use HTTP as its transport without creating a separate REST write interface. Content tools take explicit project/scope context; list_projects is a team-level discovery operation. timeline, compare and brief are P1 to match their compiled-content and UI dependencies. flag_stale submits a proposal rather than directly editing an accepted node.	P0
FR-A2	Hybrid retrieval: keyword plus embeddings, then graph expansion by typed edges.	P0
FR-A3	Responses are structured JSON with citations, confidence, as_of, freshness warnings, project of origin, resolved scope and index revision, bounded by a token budget parameter. The published API contract names a tokenizer/counting method and counts the complete serialized payload. Truncation preserves complete evidence/citation groups, reports omissions, and never drops required warnings; too-small budgets return a defined budget-too-small error rather than an uncited fragment. Transport framing and error-envelope minimums are documented separately.	P0
FR-A4	Optional brief(topic, project/scope, audience, purpose, budget) returns an accepted saved synthesis or a deterministic cited evidence bundle for a local agent to summarize. New generated prose is explicitly labeled and enters the KB only through an MCP synthesis proposal; no website or VPS-hosted generation is required. Final saved-brief versus evidence-bundle semantics remain a P1 decision.	P1
FR-A5	Agents can only submit proposals. Enforced deployments keep canonical files and service credentials outside agent-writable mounts; a readonly snapshot may be provided for inspection. A harness with unrestricted owner filesystem access cannot be claimed to satisfy this boundary. Direct file edits and generic HTTP/CLI writes are unsupported knowledge-contribution paths. Imports also submit MCP proposals. Operator backup/restore and schema migration remain maintenance operations using the shared validation rules; they cannot be used as a routine authoring bypass.	P0
FR-A6	Single canonical AGENTS.md, with thin CLAUDE.md and GEMINI.md pointers, a shared skills folder, and an install script that configures shared skills and MCP access in OpenCode, Claude, Codex and Antigravity. Symlinks are optional; a supported configuration/copy fallback preserves portability.	P0
FR-A7	Optional hook integration so a coding harness can inject relevant KB nodes at turn start, with high-confidence full items and low-confidence hints.	P2
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

7.5 Compilation and curation

ID	Requirement	Pri
FR-C1	Mark affected syntheses when inputs change; local agents discover pending refresh work through MCP and submit regenerated syntheses as proposals. Service acceptance follows policy. Until an agent refreshes them, the website displays their dependency warnings.	P1
FR-C2	Curator agent reports stale nodes, duplicates, orphans, contradictions and cross-project promotion candidates.	P1
FR-C3	Staleness: nodes past stale_after are flagged in the UI and returned with a warning by the API.	P0
FR-C4	Optional topic-cluster summaries: detect clusters in the graph and write a summary per cluster for broad questions. Enabled only when a project outgrows its syntheses.	P2

7.6 Web UI

ID	Requirement	Pri
FR-U1	Project switcher, with an "all projects" view and clear marking of shared and cross-project items.	P0
FR-U2	Global search with filters for type, audience, domain, date, confidence and project.	P0
FR-U3	Node/source pages with summary, evidence, original URL, archived revision/download and supported location preview, incoming/outgoing typed neighbors and history. Source pages list citing notes; archive/extraction availability is explicit.	P0
FR-U4	Problem to solutions to cases matrix, market datapoint table with as-of badges, timeline view, comparison view.	P1
FR-U5	Graph explorer.	P1
FR-U6	Read-only staleness list and visible evidence/freshness status. Proposal corrections, decisions and mutations remain in the MCP agent workflow.	P0
FR-U7	Audience lenses: filter presets and reading views for developers, product, project managers and sales. Agent brief templates live in shared skills; the website does not generate or author knowledge.	P1
FR-U8	Export a synthesis or timeline to slides or markdown.	P2
FR-U9	Read-only problem/topic browsing: show applicable approaches, assumptions/limitations, cases and source references; distinguish accepted typed links from labeled related-node suggestions. Tags/facets filter across groups. No internal agent or prewritten synthesis is required to render connections.	P0

Architecture summary

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.
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. 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 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.

Accepted mutations produce a git commit and a durable acceptance record before index publication. A crash between commit and indexing is recoverable by replay/rebuild; responses disclose index lag and never report an uncommitted change as accepted. Proposal decisions, redirects, run manifests, project intent and audit records must survive a full index deletion. Private source artifacts need a documented storage, access, retention and backup policy; git history alone is not a backup of files stored outside git. Backup/restore and crash-recovery acceptance tests are required for the shared-team release.

Acceptance and search visibility are separate outcomes. Receipts report accepted node revisions and index publication status. M0 must specify how a client reads the accepted revision before index publication (canonical read or a bounded wait with an explicit pending result); it must not report a committed node as nonexistent merely because indexing is delayed. Search reports its indexed revision. Crash recovery must reconcile an existing commit with its receipt before accepting a replay, including a crash between those durable writes.

One versioned operation catalog declares schemas, handlers, required capabilities and permitted transports. Generate MCP and read-only HTTP exposure from explicit allowlists; descriptive tool annotations alone do not enforce permissions. Idempotency binds proposal identity to payload digest, base revision, schema and policy versions; changed input cannot reuse an old success. Acceptance serialization needs worker fencing and recovery across git/receipt/index boundaries. Durable receipts are distinct from best-effort diagnostic telemetry. Commits contain only the accepted change set; external skills never stage unrelated user files.

External-agent skill and run contract

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 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.

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.

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.

Automatic acceptance and exceptions

Automatic acceptance is a v1 requirement. The proposed initial eligibility policy is additive source captures and evidence-backed notes/datapoints whose schema, scope, links, locations and recorded support assessments pass. This concrete starting policy is a recommendation to finalize in M0, not a user-approved list of automatic change types. Confidence alone is never sufficient. Support assessment may be performed by local agents and records its actor, source revision and rationale; it is not mislabeled as human review or deterministic proof of truth.

For routine factual notes, the proposing local agent may also assess support, as confirmed by the owner. Record the assessment and sample accepted notes for quality; no independent assessor is mandatory for every routine note. A second pass by the same model is not recorded as independent human review. Bind assessments to the exact proposed assertion/field and evidence revisions; changed assertions invalidate prior support decisions. M0 defines any higher-risk exceptions, who reviews quality samples, the sampling cadence/size, correction procedure and response when errors exceed the agreed limit. Numeric semantic-error limits are agreed before the pilot evaluation, not inferred from proposal acceptance rate. Sampling is part of pilot acceptance; it does not require an internal agent or a web review interface.

Invalid proposals return errors for agent repair. Ambiguity, destructive merges/deletions, promotions and changes outside the configured policy remain staged for an exception decision in the local agent workflow. Contradictory evidence can be added with explicit links; it must not overwrite the earlier assertion. Human-owned goals and autonomy policy retain owner authorization. Every automatic or exceptional decision records the policy version and actor and has a traceable correction/supersession path. No mandatory per-note approval or browser review workflow is introduced.

Non-functional requirements

Area	Requirement
Performance	Search under 300 ms for a project of 10,000 nodes on a laptop. brief under 5 s excluding model time.
Scale targets	10,000 nodes per project and 100,000 total, with full index rebuild under 10 minutes.
Local-first	Reading, validation of existing captures, local-file ingestion and indexing run without internet; model-assisted steps support configured local models. Fetching new external URLs requires connectivity and reports offline/unavailable explicitly. Cloud models are optional and configurable.
Portability	Plain files, no lock-in. Works on Windows, macOS and Linux. No required symlinks.
Reliability	Index is rebuildable. Every accepted canonical mutation is recorded in git; staged artifacts and run progress persist durably without requiring a commit for every intermediate file write. Ingest runs are resumable from file artifacts.
Auditability	Every node records its origin: human author or agent run/model as applicable. Every proposal decision records the authenticated actor, validation version, policy version and resulting revision.
Security	Source text is treated as data, never as instructions. Ingest agents have no write access beyond proposals. Secrets are kept out of the repo. Shared service access is authenticated and transport-protected, with revocable credentials. Fetching and parsing untrusted inputs enforce URL/network restrictions, redirect checks, file/path containment, size/time limits and parser isolation; private network fetching requires an explicit operator policy. Exact deployment controls are defined before team hosting.
Legal	Store notes, short quotes and links. Archived copies stay private. License field on every source.
Versioning	schema_version on every node and run record, with migration scripts.
Modularity	All service, agent, connector, skill/pipeline and frontend development uses explicit module ownership, public contracts and private implementations. Replaceable components have version/capability declarations, contract tests, dependency-boundary checks and state migration/rollback procedures. A compatible replacement does not require unrelated consumer changes. See the modularity protocol.
Agent-agnostic	No required use of tool-specific hooks, plugins or subagents in the core pipeline.

Success metrics

Metric	Target
Citation validity (quotes found at stated location in the cited revision)	100% of accepted factual claims and datapoints; retained unverifiable drafts do not count as accepted knowledge
Claim support	Every accepted factual claim has a recorded support decision; the benchmark separately measures semantic support errors rather than inferring correctness from quote matches
Proposal acceptance rate after tuning	At least 70% for notes, tracked per skill and per agent
Retrieval quality on a per-project question set of 20-30 questions	Correct source in the top 5 for at least 80% of questions
Cross-agent convergence	Same 5 documents through two agents produce validator-clean proposals; compare coverage of human-labeled findings and unsupported-claim rates, not wording. Numeric coverage and error thresholds are fixed before M2 acceptance.
Freshness	No datapoint older than its stale_after served without a warning
Reuse	At least one project reuses shared nodes from another project in its first month
Time to answer	A person finds a cited answer to a typical question in under 2 minutes

Milestones

Milestones describe delivery order. The owner confirmed a smaller pilot before full v1; all current P0 requirements remain the full v1 commitment. M4 and the P1 portions of M5 are optional for v1 unless explicitly selected. P0 multi-project scope, shared-policy enforcement, source retention, recovery and client compatibility cannot wait for those later milestones.

Pilot projects: Dome interactive content and an interactive video platform/service; initial team size: up to five people. Recommended pilot slice, pending exact client/format selection: one agent client and local connector, one location-preserving source format, two project scopes plus shared, source upload, same-agent recorded support, policy acceptance, cited retrieval and minimal read-only search/problem/source pages. Include viewer/editor/admin permissions, per-agent keys, invalid-evidence rejection, one retry/restart scenario and quality sampling. Demonstrate a shared source reused across both projects. Introduce this slice across M0–M3 before expanding client and format coverage. Keyword retrieval may be used during the pilot if explicitly selected; full v1 retains hybrid search. A pilot pass cannot be labeled full v1 acceptance.

Before implementing an affected boundary, M0 records a versioned decision for: (1) field/edge schemas and supported evidence locators, (2) project/shared policy ownership and support-assessor rules, (3) owner authorization and first-owner bootstrap, (4) proposal revisions, conflicts, bundle atomicity, replay and recovery, (5) accepted-revision reads during index lag, and (6) artifact limits and supported format/OS/client matrix. A lifecycle table must distinguish persisted states from retryable outcomes, and define correction, withdrawal and post-acceptance supersession. Open product decisions remain labeled pending; illustrative appendices are not executable contracts.

The full v1 release gate covers every P0 requirement plus backup/restore of canonical records and original artifacts, offline local operation, citation-safe token budgets, the declared OS/client matrix, and local-to-VPS authority handover. Each gate records its requirement, fixture, expected outcome, measured result and evidence link. NOT RUN or BLOCKED is not a pass. Fix benchmark hardware, workload, percentile, embedding-cache assumptions, semantic-error limits and recovery objectives before measuring against the success metrics; the current numeric targets are unverified targets.

Milestone	Scope	Exit criteria
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.
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.

Risks and mitigations

Risk	Mitigation
Different agents extract inconsistent notes	Shared schema, validator gate, golden test documents, short example-driven skills
Hallucinated or misquoted claims	Quote-location validation, separate verify step, second agent for verification where possible
Low-value auto-captured notes	Lens-based triage, evidence/support checks, constrained automatic acceptance and quality sampling
Projects pollute each other	Required project_id, scoped queries, per-project lens fit, explicit cross-project edges, promotion only through review
Duplicate sources and entities across projects	Dedupe identical captures by hash, use URLs to resolve source identities without dropping changed revisions, and review entity resolution in the shared layer
Prompt injection from ingested sources	Treat source text as data, restrict ingest agent permissions, no direct writes
Market data goes stale	as_of and stale_after required for datapoints, curator reports, API warnings
Vendor or tool lock-in	Files plus MCP, no dependence on any one agent's hooks or plugins
Index drift	Index is derived and rebuilt from files, with a doctor command to check it
Over-building the stack (graph server, extra pipeline stages)	Start with files, SQLite and typed tools. Revisit a graph engine, clustering or heavier entity matching against measured limits described in the architecture summary.

Open questions

Confirmed target: shared team plus local agents, all-team read access, local development then the owner’s VPS, read-only website, MCP-only knowledge contributions and policy-controlled automatic acceptance. Fine-grained project confidentiality remains P2. The following decisions are unresolved; recommendations in the review report are not approvals.

1. Should KB live in its own repo or inside one of the existing agent repos?
2. Embedding model: local or API, and how to handle re-embedding when the model changes?
3. What VPS capacity, backup responsibility and simultaneous user/agent/ingestion workload must v1 support? Local development followed by the owner’s VPS is confirmed.
4. Who owns each project and shared-library policy, and how is owner authorization for protected changes recorded through the local-agent/MCP workflow?
5. Which shared-library changes are eligible for automatic acceptance, and which require exception review?
6. How should NotebookLM exports be captured: manual export, or an automated step?
7. Which representative sources/questions and subtypes are needed for the confirmed Dome interactive content and interactive video platform/service pilot? Suggested IDs are dome-performance and interactive-video; exact IDs remain to be finalized.
8. Finalize the automatic-acceptance eligibility proposed above, support-assessment requirements and exception handling. Human approval of every proposal is explicitly not required.
9. Which P1 features are release requirements? In particular, is a compiled brief required for the first useful team workflow, or can cited search/node retrieval satisfy it?
10. What are the private archive size/retention, backup/restore targets, benchmark hardware, concurrent workload and query-budget distribution?
11. Which source formats, initial client/OS pair and retrieval mode should the confirmed smaller pilot demonstrate? Full v1 retains the existing P0 commitments.
12. Who operates quality sampling, at what sample size/cadence and semantic-error threshold? Same-agent extraction and support assessment for routine factual notes are confirmed.

Appendix A. Example project registry entry

Illustrative only: the automatic eligibility and support checks must be specified alongside these modes before implementation; the exact initial policy remains open question 8.

---
project_id: interactive-video
title: Interactive video knowledge
status: active
description: Research supporting interactive video projects
owners: [example-owner]
north_star: <main goal, human-owned>
key_questions:
  - How do others control branch explosion at feature-film scale?
  - Who pays for interactive video, and how much?
audiences: [dev, product, pm, sales]
default_includes: [shared, agentic-design]
autonomy_policy: {source: auto-merge-safe, note: auto-merge-safe, datapoint: auto-merge-safe}
---

The confirmed pilot covers Dome interactive content and an interactive video platform/service. dome-performance and interactive-video are suggested IDs; agentic-design remains an example rather than a third pilot commitment.

Appendix B. Example note

Illustrative draft, not a validator fixture: the source, source revision, quote, linked problem and run below must be replaced with actual records before acceptance.

---
id: interactive-video:state-variables-vs-branching
project_id: interactive-video
type: technique
title: Track state variables instead of multiplying branches
summary: Store choices as flags or values and vary scenes by state so paths do not multiply with each choice.
audience: [dev, product]
domain: [tech, design]
confidence: medium
review_state: draft
lifecycle: active
created: 2026-10-12
updated: 2026-10-12
tags: [state-tracking]
run_id: example-run
agent: example-agent
model: example-model
claim_support: pending
solves: [interactive-video:combinatorial-explosion]
lens_fit:
  interactive-video: {score: 0.9, horizon: H3, key_question: branch explosion, reason: addresses the project question}
  agentic-design: {score: 0.4, horizon: H2, reason: state tracking in agent workflows}
derived_from:
  - {source: shared:src-example-talk, revision: example-revision, quote: "<exact transcript quote required>", loc: "t=14:32; span=<required>"}
schema_version: 1
---

Appendix C. Agent tool signatures (illustrative)

Content requests require scope_context = {project, includes?} or an explicitly selected projects/all scope. The server resolves and returns effective scope; the same scope rules apply to redirects and resources. Authenticated actor identity comes from credentials, not these arguments. Content responses use the budget contract in FR-A3; proposal/decision receipts have a separate documented size limit.

search(query, scope_context, token_budget, filters={}, limit=10)
get_node(id, scope_context, token_budget)
neighbors(id, scope_context, token_budget, edge_types=[], depth=2)
timeline(topic, scope_context, from, to, token_budget)                 # P1
compare(ids, scope_context, token_budget)                             # P1
brief(topic, scope_context, audience, purpose, token_budget)           # P1
list_projects()
propose_note(scope_context, node_bundle, run_id, proposal_id, base_revision)
flag_stale(id, scope_context, reason, proposal_id, base_revision)       # stages a proposal

Resources: kb://schema, kb://projects/{project_id}, kb://nodes/{id}. Prompts: per-project roles, for example architecture_advisor(project_type, budget_tier) for interactive-video.

MCP additionally needs typed source-artifact transfer and proposal operations to list/get status, inspect validation, submit revisions/support assessments, withdraw a draft and request policy evaluation. Exact schemas are an M0 deliverable. The service performs acceptance under policy; agents cannot invoke an unconditional merge or impersonate owner authorization. Protected changes need attributable owner authorization through the MCP workflow. The website and generic HTTP/CLI interfaces provide no contribution or acceptance path.

Revision notes (0.3)

• Confirmed shared-team and agent target, all-team read access, and P0 authentication/mutation permissions while preserving P2 project confidentiality.
• Defined scope propagation, source revision evidence, separate claim-support review, freshness dimensions, stable rename/promotion behavior, and the limits of local-file write isolation.
• Added concurrent proposal acceptance and recovery requirements; aligned P0/P1 tool exposure and corrected the storage rationale.
• Repaired illustrative examples and documented unresolved release, deployment, benchmark and autonomy decisions. These are requirements and proposals, not claims of implementation or passing tests.

Revision notes (0.4)

• Applied owner clarification: local development then VPS deployment; local agents remain the writers through MCP; the website only searches and displays knowledge.
• Promoted automatic acceptance policy to P0, replaced browser review with MCP exception handling, and removed alternate HTTP/CLI/direct-file contribution paths.
• Defined source-artifact transfer to the VPS and local-to-VPS authority handover. Explained compiled briefs as optional agent-produced summaries with citations; their launch scope remains undecided.

Revision notes (0.5)

• Confirmed no internal reasoning agent initially; external local agents supply semantic analysis while service functions validate, index and serve records.
• Specified source-file/URL intake, original artifact storage, citation revision/location navigation and a proposed local MCP transfer connector. Protocol support is distinguished from unimplemented KB upload tooling.
• Added problem/topic browsing, typed solution relationships with conditions, tag filtering and labeled similarity suggestions. Added P0 FR-U9; graph canvas and rich comparison matrices remain P1.

Revision notes (0.6)

• Applied the implementation review of Jev and SCAR/Winnow, preserving the no-internal-agent and MCP-only contribution boundaries.
• Added durable external-run manifests/bounded resumption (FR-I11) and capability/version diagnostics (FR-A10), both P0.
• Clarified external skill contracts, explicit project intent, structured support assessments, source location maps, transport authorization, content-bound replay and durable acceptance receipts.
• Required per-client/deployment workflow evidence; source projects' existing code or documentation do not establish KB acceptance.

Revision notes (0.7)

• Reviewed the current PRD against GOAL.md and recorded remaining decisions in the readiness report.
• Clarified shared-policy authority, bundles spanning policy domains, support-assessor decisions and assertion-bound assessment validity.
• Clarified accepted-revision reads during index lag and P0 dependency warnings for displayed syntheses.
• 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.