---
decision_id: adr-knowledge-configuration-v1
decision_title: Knowledge Configuration v1
decision_status: accepted
decision_scope: knowledge-configuration
decision_owner: platform
---
# ADR: Knowledge Configuration v1

## Status

Accepted as the v1 production contract for OpenClerk-compatible knowledge
vaults on the current AgentOps surface.

This ADR defines the contract agents can rely on through the installed
`openclerk` JSON runner and `skills/openclerk/SKILL.md`. It does not require a
committed manifest file. `oc-za6.2` promoted runner-derived layout inspection
through `inspect_layout` and kept the underlying v1 layout convention-first.

## Context

OpenClerk is a local-first, agent-facing knowledge plane. Routine agents need
to create, inspect, retrieve, synthesize, and explain local knowledge without
reading implementation files, backend variants, module caches, SQLite directly,
HTTP/MCP internals, or source-built command paths.

The v1 configuration contract therefore has to be visible through AgentOps:
the installed `openclerk config`, `openclerk document`, and
`openclerk retrieval` JSON runners plus the shipped skill instructions. A
production agent should be able to explain
where the vault is, which markdown files are canonical, which derived records
or projections are fresh, and which source evidence supports a synthesis page
using only runner JSON results.

The existing architecture direction already accepts canonical markdown docs,
source-linked synthesis, promoted records, provenance events, projection
freshness, and eval evidence as the path toward durable agent-maintained
knowledge. This ADR turns those ideas into the v1 knowledge configuration
contract.

## Decision

OpenClerk knowledge configuration v1 is runner-visible and convention-first.

An OpenClerk-compatible vault is defined by:

- runner-resolved storage paths for the effective database path and configured
  vault root
- vault-relative markdown paths under the vault root
- document frontmatter and section conventions for first-class document kinds
- runner-maintained document registry entries with stable ids, chunk ids,
  headings, metadata, and citations
- derived SQLite projections for graph, records, services, provenance, and
  projection freshness that remain explainable through runner JSON

The conventional layout is part of the product contract:

- the configured vault root is the markdown knowledge root.
- `sources/` is the conventional home for canonical source docs.
- `synthesis/` is the conventional home for source-linked synthesis.
- record-shaped and service-shaped markdown conventions feed promoted record
  projections.
- `source_refs`, `## Sources`, and `## Freshness` are conventional synthesis
  evidence and freshness fields.
- the database path is the routine storage anchor. The vault root is stored in
  SQLite runtime configuration and is visible through runner path resolution.

No committed manifest, schema file, or separate configuration document is
required for v1. `inspect_layout` is the runner-visible configuration model:
it explains the effective conventions and reports invalid or incomplete
layouts through JSON checks without making a committed artifact authoritative.

## V1 Concepts

Canonical docs are markdown files under the vault root. They have stable
`doc_id`, `chunk_id`, vault-relative `path`, headings, parsed frontmatter
metadata, timestamps, and citations exposed by runner results. Canonical docs
are the default source of truth for local knowledge.

Canonical source docs are canonical docs used as source authority for later
answers, synthesis pages, or promoted records. They conventionally live under
`sources/`, but source authority comes from runner-visible citations, paths,
chunk ids, metadata, provenance, and freshness, not from folder naming alone.

Synthesis docs are durable compiled knowledge pages that summarize or reconcile
canonical evidence. They conventionally live under `synthesis/` with
frontmatter containing `type: synthesis`, `status: active`,
`freshness: fresh`, and single-line comma-separated `source_refs`. They include
`## Sources` and `## Freshness` sections. Synthesis docs do not outrank the
canonical source docs or promoted records they cite.

Promoted records are selective structured projections derived from canonical
markdown docs when a domain benefits from typed lookup. Generic record-shaped
docs use record frontmatter and facts. The service registry is the first typed
promoted-domain prototype, exposed through service-specific lookup and record
actions. Promoted records remain derived from canonical markdown and must keep
citations and freshness inspectable.

Provenance events are runner-visible append-only facts about document changes,
source changes, projection invalidations, projection refreshes, and record or
service extraction. They explain how a document, record, service, or projection
was created or refreshed.

Projection freshness is the runner-visible current state for derived outputs.
Projection states report freshness, projection version, observed time, and
details for derived graph, record, service, or synthesis outputs. The
`synthesis` projection is the v1 freshness contract for source-linked synthesis
and can explain current, stale, missing, or superseded source refs.

Eval evidence is the committed reduced proof that the production AgentOps
surface satisfies the contract. Reports under `docs/evals/results/` use
repo-relative paths and neutral artifact placeholders such as `<run-root>`.
They gate runner use, source authority, citations, freshness, final-answer-only
rejections, and bypass prevention.

## OpenClerk-Compatible Vault

A vault is OpenClerk-compatible for v1 when an agent can use runner JSON to
resolve paths, validate or create markdown documents, list and retrieve
canonical docs, find source evidence, inspect derived records, inspect
provenance, and inspect projection freshness.

Compatibility requires these observable properties:

- `openclerk document` can resolve the effective database path and configured
  vault root.
- documents use vault-relative paths and markdown bodies accepted by
  `validate` or `create_document`.
- canonical docs are discoverable through `list_documents`, `get_document`,
  and `search` without direct vault inspection.
- source-sensitive answers can cite runner-visible paths, `doc_id`, `chunk_id`,
  headings, line ranges, source refs, or provenance.
- synthesis pages under `synthesis/` preserve `type: synthesis`,
  `status: active`, `freshness: fresh`, `source_refs`, `## Sources`, and
  `## Freshness`.
- promoted records and services remain derived from canonical markdown and are
  inspectable through records, services, provenance, and projection-state
  runner actions.
- stale, missing, superseded, or refreshed derived knowledge is explainable
  through projection states and provenance events.

The database is an implementation detail for the runner. It may contain the
document registry, chunks, search indexes, links, projections, provenance, and
promoted records, but routine agents must not query it directly.

## Runner Contract

The v1 document runner actions are:

- `validate` checks document request shape without writing a document.
- `resolve_paths` exposes the effective OpenClerk data, database, and vault
  paths.
- `inspect_layout` exposes the convention-first layout contract, conventional
  prefixes, first-class document kinds, and pass/warn/fail validation checks.
- `create_document` writes a new canonical markdown document and registers it.
- `compile_synthesis` creates or updates exactly one source-linked synthesis
  page under `synthesis/`, preserves single-line source refs, requires
  `## Sources` and `## Freshness`, reports duplicate status, provenance refs,
  projection freshness, write status, validation boundaries, and authority
  limits.
- `ingest_source_url` downloads a PDF source URL into a configured vault asset
  path, creates or explicitly updates the canonical markdown source note, and
  returns validated retrieval/provenance metadata.
- `list_documents` exposes document registry entries by path prefix or metadata.
- `get_document` returns a canonical document by stable `doc_id`.
- `append_document` appends durable markdown content to an existing document.
- `replace_section` replaces one named markdown section while preserving the
  rest of the document.

The v1 config runner actions are:

- `inspect_config` reports effective configuration, including storage paths and
  database source, default profile autonomy modes, non-secret module summaries,
  and git lifecycle checkpoint gate posture.
- `configure_profile` persists default autonomy/profile modes under the
  database-backed runtime configuration namespace.
- `clear_profile` removes persisted default profile overrides and returns to
  built-in defaults.

Request-level `document` and `retrieval` `autonomy` fields override persisted
profile defaults field-by-field. Optional provider settings remain under
`openclerk module configure_module`; profile configuration is not module
configuration. Vault-root binding is storage bootstrap configuration: it is
initialized or intentionally rebound only through `openclerk init --vault-root`,
while `inspect_config.storage` reports it read-only. Git checkpoint enablement
remains invocation-scoped through `--git-checkpoints` or
`OPENCLERK_GIT_CHECKPOINTS`; `inspect_config` reports that persistence is
unsupported rather than adding a durable checkpoint flag.

The v1 retrieval runner actions are:

- `search` finds source-grounded document chunks with citations.
- `document_links` exposes outgoing markdown links and incoming backlinks.
- `graph_neighborhood` exposes derived docs graph context.
- `graph_context_report` packages routine relationship graph context with
  source identity, canonical markdown relationship text, links/backlinks,
  graph projection freshness, provenance refs, and authority limits.
- `graph_relationship_report` packages relationship paths, direct-vs-derived
  evidence, typed candidates from canonical markdown, limited
  stale/orphaned/contradiction audit findings, graph projection freshness,
  provenance refs, and authority limits.
- `graph_relationship_maintenance_plan` packages approval-before-write
  canonical markdown relationship maintenance candidates with exact next
  replace/append requests, duplicate handling, rollback/audit path, failure
  modes, freshness, provenance refs, and `planned_no_write`.
- `records_lookup` finds promoted generic record entities.
- `record_entity` returns one promoted generic record entity.
- `services_lookup` finds promoted service records.
- `service_record` returns one promoted service record.
- `decisions_lookup` finds promoted decision records with status, scope, owner,
  and text filters.
- `decision_record` returns one promoted decision record by stable decision ID.
- `source_audit_report` explains source-sensitive audit evidence and can repair
  only an existing synthesis target in `repair_existing` mode while preserving
  citations, provenance, freshness, duplicate prevention, and unresolved
  current-source conflicts. It is not a broad contradiction engine.
- `evidence_bundle_report` packages read-only records, decisions, exact
  evidence by supplied IDs, provenance events, projection freshness, citations,
  validation boundaries, and authority limits without adding new storage.
- `provenance_events` exposes derivation, update, invalidation, and refresh
  history.
- `projection_states` exposes current derived freshness and version state.

These actions are the production agent interface for explaining and validating
knowledge layout. Unsupported lower-level workflows should be rejected rather
than routed around the runner.

## `oc-za6.2` POC Decision

Decision: promote runner-derived layout inspection and keep v1
convention-first. A committed manifest or separate config artifact is not
needed for v1.

The POC compared three options:

- convention-first only: paths, frontmatter, and discovery are enough for
  routine operation, but agents needed too many separate reads to explain why a
  layout is valid or invalid.
- runner-derived inspection: `inspect_layout` can explain the configured
  layout and report incomplete synthesis, source refs, record, and service
  identity conventions through one JSON result.
- committed config artifact: deferred or killed for v1 because it would create
  a second source of truth without improving canonical markdown authority.

The promoted model is therefore not a manifest. It is a runner-visible
inspection result derived from canonical markdown registry state. Targeted
AgentOps evidence is recorded in
`docs/evals/results/ockp-layout-configuration.md`: both
`configured-layout-explain` and `invalid-layout-visible` passed while
preserving the no broad repo search, no direct SQLite, and no source-built
runner invariants.

## `oc-za6.3` POC Decision

Decision: keep the existing document and retrieval actions for source-linked
synthesis maintenance. Do not promote a dedicated synthesis/compiler action for
v1 from this POC alone.

The POC pressure-tested the current workflow against candidate-selection,
multi-source creation, stale repair, mixed records/synthesis, and resumed
multi-turn drift repair. The selected pressure scenarios required agents to
search source evidence, list `synthesis/` candidates, retrieve existing
synthesis before editing, inspect synthesis projection
freshness where relevant, preserve single-line `source_refs`, keep
`## Sources` and `## Freshness`, and update without duplicate synthesis pages.

Targeted AgentOps evidence is recorded in
`docs/evals/results/ockp-synthesis-compiler-pressure.md`. This was a targeted
run, not a full production-gate run: all 12 selected synthesis, pressure, and
contract-enforcement scenarios passed; the production gate remained false only
because unrelated scenarios were intentionally not selected. The selected run
also preserved the no broad repo search, no direct SQLite, no source-built
runner usage, no-tools invalid-request handling, and citation/source
freshness invariants.

## Workflow Action Promotion Addendum

Later candidate-comparison work selected Candidate C for three high-ceremony
tracks: promote one narrow runner-owned workflow action while keeping the
existing primitives for advanced/manual cases. This addendum updates the v1
runner contract without changing canonical markdown authority, storage schema,
or bypass boundaries:

- `oc-e8om`: promote `compile_synthesis` for routine source-linked synthesis
  creation/update and keep document/retrieval primitives for manual repair.
- `oc-w8x0`: promote `source_audit_report` for narrow source-sensitive audit
  explain/repair and keep broad contradiction-engine claims rejected.
- `oc-lrqi`: promote read-only `evidence_bundle_report` for records,
  provenance, decision, and projection evidence bundles while keeping the
  underlying lookup primitives available.

The promotion reason is UX evidence: repeated prompt choreography, exact JSON
recipes, and step ordering proved capability but created taste debt. The skill
remains a compact router and safety contract rather than the long-term home for
multi-step workflow recipes.

The deferred candidate action shape remains:

```json
{
  "action": "compile_synthesis",
  "synthesis": {
    "path": "synthesis/example.md",
    "title": "Example",
    "source_refs": ["sources/source-a.md", "sources/source-b.md"],
    "body": "# Example\n\n## Summary\n...\n\n## Sources\n...\n\n## Freshness\n...",
    "mode": "create_or_update"
  }
}
```

Release-prep amendment: the workflow-action promotion rubric now treats
repeated prompt choreography as UX evidence, not as a reason to keep expanding
`skills/openclerk/SKILL.md`. This means the `oc-za6.3` non-promotion is no
longer sufficient as a final answer if natural synthesis maintenance requires
exact JSON, literal command ordering, or workflow-specific skill recipes.
Future work must compare at least three surfaces before closing the track:
current primitives with a smaller skill, one narrow `compile_synthesis` or
`maintain_synthesis` runner action, and a combined narrow action plus existing
primitives for advanced/manual cases. The comparison must report
tool/command count, assistant turns, prompt specificity, failure/retry rate,
safety pass, capability pass, and UX quality.

## `oc-jb0` POC Decision

Decision: promote `openclerk document` action `ingest_source_url` for PDF source
URL ingestion.

The current document and retrieval actions can create markdown source notes,
index retrieval text, and expose provenance, but they cannot download a PDF,
register the binary asset, compute hash/size/page count, extract PDF
metadata/text, reject duplicate source URLs, and return a single validated
source-note/asset/provenance result. Requiring routine agents to orchestrate
those steps outside the runner would create brittle HTTP, filesystem, PDF, and
duplicate-detection bypass work.

The promoted action accepts `source.url`, `source.path_hint`,
`source.asset_path_hint`, and optional `source.title`. It stores the PDF under
the configured vault asset path, creates a canonical `sources/*.md` source note
with `modality: markdown` and `source_type: pdf`, indexes extracted or
metadata-derived retrieval text through the existing markdown chunk path, and
returns the created document id, source path, asset path, derived path,
citations, hash, size, MIME type, page count, capture timestamp, and optional
PDF metadata.

Targeted evidence is recorded in
`docs/evals/results/ockp-source-url-ingestion-poc.md`. The promoted surface
preserves canonical markdown authority, source provenance, duplicate handling,
retrieval citations, and vault-relative paths. Update/re-ingest behavior stays
out of scope until a separate issue defines its conflict and stale-state
semantics.

## `oc-n31` Contract Decision

Decision: keep `ingest_source_url` create-only by default and support explicit
update mode for re-ingesting an existing PDF source URL.

The request shape includes optional `source.mode`. Missing mode means `create`,
preserving the current duplicate `source_url` rejection. `update` targets the
existing source document by normalized `source.url`; it must not create a new
source document when the URL is unknown. Existing source and asset paths remain
stable, and any supplied `source.path_hint` or `source.asset_path_hint` must
match the stored source metadata or return a conflict without writing.

Update mode compares the downloaded PDF SHA256 before mutating durable state.
If the SHA256 matches the stored source metadata, the request is a no-op:
return the existing source ingestion result, preserve citations, and avoid
projection invalidation or extra stale-state churn. If the SHA256 changes, the
runner atomically replaces the PDF asset and generated source note while
preserving the source note `doc_id` and path so existing source refs and
retrieval citations continue to resolve.

Changed updates emit source provenance that records previous and new SHA256
values, asset path, source URL, page count, and capture timestamp. Search chunks
must be refreshed before success. Any synthesis that references the updated
source must become visibly stale through projection state and provenance before
the update returns success, so agents can inspect freshness before answering
from derived text.

Required implementation coverage:

- duplicate URL in default `create` mode still rejects
- `update` for a missing source URL returns not found and writes nothing
- `update` with mismatched source or asset path returns conflict and writes
  nothing
- same-asset `update` returns unchanged/no-op and preserves citations
- changed-asset `update` rewrites asset metadata, extracted text, citations,
  provenance, and stale synthesis state
- failed `update` leaves the previous source note, asset, and indexed state
  intact

## `oc-v1ed` Web URL Intake Decision

Decision: extend `openclerk document` action `ingest_source_url` to support
public HTML/web-page and Markdown source ingestion under the same runner-owned
URL intake surface.

The request shape adds optional `source.source_type`. `source_type: "pdf"`
keeps the existing PDF behavior and still requires `source.path_hint` plus
`source.asset_path_hint` in create mode. `source_type: "web"` creates a
canonical `sources/*.md` web source note from public HTML or Markdown and
requires `source.path_hint`; `source.asset_path_hint` is not used. GitHub
repository landing URLs normalize to the public raw README, and GitHub Markdown
blob URLs normalize to their public raw content URL. When `source.source_type`
is omitted, the runner detects PDF versus HTML/Markdown from the URL and
response. Unsupported content types reject without writing.

The request shape also supports `source.mode: "inspect"` as a read-only URL
artifact/source intake plan. Inspect mode performs a runner-owned bounded fetch
of the supplied public URL, extracts a text preview and bounded discovered links
for web/Markdown sources, checks duplicate source URL placement, and returns
approval-ready primary and related `ingest_source_url` requests. `mode: "plan"`
remains the no-fetch placement-only surface.

A user-provided URL is sufficient permission for the runner to fetch the page;
agents must not ask for a separate pre-fetch approval. Durable writes still
require complete runner fields or an approved candidate workflow when required
fields are missing.

Safety pass: inspect mode uses the same public URL validation, redirect policy,
content-type handling, duplicate lookup, runner-only transport, and durable
write approval boundary as create/update. It does not authorize browser
automation, private networks, login-gated pages, recursive crawling, direct
vault inspection, direct SQLite, or source-built runner bypass.

Capability pass: inspect mode can turn a public README, Markdown page, HTML
page, or PDF URL into a primary source candidate and related source candidates
without asking the user for premature path hints. It preserves create/update
ingestion as the only durable source authority path.

UX quality pass: public URLs are treated as explorable intake artifacts instead
of forcing exact prompt choreography around path placement. The agent can answer
from `source_url_intake_plan.agent_handoff`, show next approved requests, and
delay durable-write approval until the user chooses which sources to ingest.

Web source notes use canonical markdown authority with `type: source`,
`source_type: web`, `modality: markdown`, normalized `source_url`,
`derived_path`, SHA256 content hash, MIME type, capture timestamp, and visible
HTML text or Markdown content. Create mode rejects duplicate normalized source
URLs. Update mode targets the existing web source by normalized `source.url`,
preserves `doc_id` and path, no-ops on unchanged content hash, and marks
dependent synthesis stale when fetched visible content changes.

Product-page behavior is public-visible only. Committed documentation uses
neutral placeholders such as `<amazon-product-url>`, `<product-title>`, and
`<tracking-query>`. The runner and skill do not authorize login, account state,
captcha, paywall access, cart state, checkout, purchase actions, private
network acquisition, browser automation, direct vault writes, or agent-side
HTTP/MCP acquisition.

Targeted coverage is defined in
`docs/evals/web-url-intake-pressure.md`. The lane covers missing path hints,
web create, duplicate normalized URL rejection, same-hash no-op update,
changed web content with stale synthesis visibility, and unsupported
acquisition rejection.

## `oc-za6.4` POC Decision

Decision: promote decision and architecture records as the second typed
promoted domain after services.

Canonical markdown remains authoritative. Decision projection is driven by
frontmatter fields such as `decision_id`, `decision_title`, `decision_status`,
`decision_scope`, `decision_owner`, `decision_date`, `supersedes`,
`superseded_by`, and `source_refs`; ADR-like filenames are useful conventions
but are not required. `records/decisions/` is a conventional home, while ADRs
or decision notes under other paths are valid when the metadata is present.

The POC adds `decisions_lookup` and `decision_record` because decision-centric
tasks benefit from typed status/scope/owner filters, stable repeatable lookup,
update safety, citations, and supersession freshness. Plain docs search remains
useful for broad discovery, but it is weaker for questions such as "what is the
current accepted decision?" when old and current decisions coexist.

Decision projection freshness treats current decisions as fresh. Superseded
decisions or decisions with `superseded_by` are stale, with projection details
that expose the replacement IDs and freshness reason; replacement decisions
with `supersedes` remain fresh when their canonical markdown source is current.

Targeted AgentOps evidence is recorded in
`docs/evals/results/ockp-decision-records-poc.md`. The targeted run covers
decision-vs-doc precision, supersession freshness, no broad repo search, no
direct SQLite, no source-built runner usage, final-answer-only invalid-request
rejection, and preserved citations/source refs/freshness.

Follow-up hardening evidence for `oc-j0a` is recorded in
`docs/evals/results/ockp-decision-records-hardening.md`. The targeted partial
run covers migrated real ADR markdown under `docs/architecture/`, widened
decision text lookup, explicit `decision_record` supersession checks, fresh
decision projection states, provenance, and repo-relative citation paths. All
3 selected decision scenarios passed; the production gate remained false only
because unrelated scenarios and final-answer-only validation scenarios were not
selected in that partial run.

## `oc-za6.5` POC Decision

Decision: keep source-sensitive audit and contradiction-like workflows as a
reference pattern on existing provenance and freshness primitives. Do not
promote a broad semantic contradiction engine or a new audit runner action for
v1 from this POC alone.

The POC stays narrow: agents search canonical sources, list existing synthesis
candidates, retrieve the target synthesis before editing, inspect synthesis
projection freshness and provenance, then repair stale synthesis without
creating duplicates. When current sources conflict and no supersession metadata
or other runner-visible source authority chooses a winner, agents should
explain the unresolved conflict with both source paths instead of asserting a
general contradiction result.

Targeted AgentOps evidence is recorded in
`docs/evals/results/ockp-source-sensitive-audit-poc.md`. The targeted run
covers stale audit repair, unresolved conflicting current sources, existing
stale-synthesis repair workflows, no broad repo search, no direct SQLite, no
source-built runner usage, no-tools invalid-request handling, and preserved
citations/source refs/freshness. All 8 selected scenarios passed; the
production gate remained false only because unrelated scenarios were
intentionally not selected.

Release-prep amendment: under the revised workflow-action rubric, a passing
scripted audit run proves capability and safety only. It does not prove UX if
routine agents need exact search, candidate-selection, provenance, projection,
and repair choreography. The valid user need remains source-sensitive audit
and repair, but the broad semantic contradiction-engine shape remains
unsupported. Follow-up work must compare current primitives with a smaller
skill, one narrow source-sensitive audit workflow action, and a combined
package-and-explain action plus existing primitives for advanced/manual
repair. The comparison must preserve unresolved-conflict explanation, source
authority, citations, provenance, freshness, duplicate handling, runner-only
access, and approval-before-write.

## `oc-za6.6` POC Decision

Decision: keep richer graph semantics as a reference pattern and do not promote
a semantic-label graph layer for v1.

The POC keeps relationship meaning in canonical markdown. Agents can search for
relationship words such as requires, supersedes, related to, and
operationalizes; inspect the source document; expand outgoing links and
incoming backlinks; inspect the derived graph neighborhood; and verify graph
projection freshness. The derived graph remains structural and cited: edge
kinds such as `links_to` and `mentions` explain navigation, while canonical
markdown remains the source of semantic relationship authority.

Targeted AgentOps evidence is recorded in
`docs/evals/results/ockp-graph-semantics-reference-poc.md`. The targeted run
covers graph semantic-label pressure, canonical docs navigation, no broad repo
search, no direct SQLite, no source-built runner usage, final-answer-only
invalid-request rejection, and preserved citations/source refs/freshness. No
follow-up implementation issue is filed because the POC decision is reference
and deferred rather than promoted.

## `oc-za6.7` POC Decision

Decision: keep memory and autonomous routing as reference/deferred benchmark
pressure and do not promote a production memory/router interface for v1.

The POC evaluates temporal recall, session promotion, feedback weighting, and
routing by requiring agents to use existing AgentOps document and retrieval
actions. Session-derived material becomes useful only when it is canonicalized
as markdown with source refs. Temporal and feedback signals are advisory unless
the answer also preserves source paths, provenance, and projection freshness.
Routing remains an explainable choice among existing runner actions rather than
a hidden autonomous router or memory-first authority.

Targeted AgentOps evidence is recorded in
`docs/evals/results/ockp-memory-router-reference-poc.md`. The targeted run
covers memory/router reference pressure, no broad repo search, no direct
SQLite, no source-built runner usage, final-answer-only invalid-request
rejection, and preserved citations/source refs/freshness. No follow-up
implementation issue is filed because the POC decision is reference and
deferred rather than promoted.

## Production-Valid for AgentOps

A vault is valid enough for production AgentOps use when:

- routine create, list, retrieve, search, synthesis, record, provenance, and
  freshness workflows are expressible through documented runner actions
- required request fields clarify or reject with understandable no-tools
  behavior while invalid limits remain explicit rejects
- source-sensitive answers preserve citations, source refs, chunk ids, paths,
  provenance, or projection-state details
- synthesis is updated rather than duplicated when an existing page already
  covers the topic
- canonical docs and promoted records outrank synthesis
- derived graph, record, service, and synthesis outputs expose freshness or
  provenance sufficient to explain their relationship to canonical docs
- routine agents do not inspect implementation files, backend variants, module
  caches, generated server files, SQLite directly, HTTP/MCP transports, or
  source-built runner paths
- selected production AgentOps evals pass and their reduced reports are
  committed under `docs/evals/results/`

Production validity is a product and eval contract, not a promise that every
possible markdown folder is semantically complete. Missing conventions,
unsupported document kinds, stale projections, or weak citation evidence should
surface as runner-visible validation gaps, stale freshness, missing results, or
follow-up work.

## Non-Goals

Knowledge configuration v1 does not include:

- autonomous routing across docs, records, graph, and future memory
- memory-first `remember` or `recall` semantics
- a rich semantic graph as an independent truth system
- an HTTP or MCP daemon as a routine production agent surface
- multi-user corporate memory
- a required committed vault manifest
- a dedicated synthesis runner action
- direct SQLite, backend variant, module-cache, source-built runner, or ad hoc
  runtime workflows for routine agents
