DevOps Wiki Product Vision

Status: draft product vision Date: 2026-05-19

The wiki should become the glue between product vision, implementation, quality, and operations. It is not just a document site. It is the shared operational memory layer for humans, coding agents, QA agents, and ops agents.

The working product label is a DevOps wiki: a Markdown-native knowledge platform where QA, Ops, MCP tools, and the implementation can all refer to the same pages, entities, evidence, and decisions.

Principle

Everything follows the established perspective order:

1. API first
2. MCP second
3. UI third

The API owns graph projections, indexes, checkpoint state, code maps, and evidence records. MCP tools wrap that API for agents. The UI is the human surface over the same model.

Storage model

The live wiki should not write Markdown files or R2 objects on every edit.

• Markdown/frontmatter and source annotations are the durable knowledge source.
• Git is the checkpoint/archive log.
• FalkorDB is the materialized graph and traversal store.
• Product databases hold live operational records such as QA queue rows and ops events/anomalies.
• R2 is for binary assets only: images, attachments, screenshots, export bundles, and similar blobs.

The wiki can flush to Git on a schedule, after a change threshold, or through a manual "checkpoint now" operator action. The Git module belongs in the shared chrome, not as a main tab:

Git: 42 live changes, last checkpoint 19h ago, checkpoint now, view diff

The core invariant is reconstruction:

Markdown/source annotations + operational records -> materialized graph -> Git checkpoint

If FalkorDB is lost, Git/Markdown plus product databases rebuild it. If Git is behind, the UI must show the dirty/checkpoint state clearly.

Active tab slice

This sprint's top-level wiki UI focuses on five tabs, in navigation order:

Atlas | Canon | Codebook | Journal | Librarian

Journal remains one of the nine graph hubs and a Wiki projection. It is a first-class tab for temporal memory, and it also remains reachable through Atlas, Librarian, backlinks, and direct document routes.

Atlas

Atlas is the map of the knowledge base.

It must be more than a decorative graph. It should offer two connected ways to read the system:

1. A traditional book/chapter view for deliberate reading.
2. A graph/neighborhood view for discovering what connects.

The useful version is a "map plus shelf":

• product shelves: CareerVector, JobCache, shared platform;
• chapter spines: Architecture, Runbooks, Stories, Studies, Decisions, Implementation, Journal;
• local neighborhoods: focused graph around the current page or entity;
• trails: suggested read-next paths for humans and agents;
• filters by the nine hub types: idea, behaviour, implementation, suite, test, anomaly, infra, event, journal;
• orphan and weak-link views to show where the knowledge graph needs care.

Atlas is also the machine routing surface. Agents should be able to ask:

• What should I read before changing this service?
• What pages explain this incident?
• What behaviours and tests touch this code path?
• What decisions led to this architecture?

Canon

Canon is the product memory.

It holds the durable "why":

• product vision;
• principles;
• architecture decisions;
• what the product is and is not;
• audience and non-audience;
• boundaries between CareerVector and JobCache;
• vocabulary and naming discipline;
• long-running tradeoffs.

Canon is bigger than user stories. It is the reference layer an agent should read before proposing a direction.

Codebook

Codebook is the implementation map.

It should be generated where possible, but curated by structure rather than dumping every private helper into a wall of text. It should answer questions like:

• Where is the shared header/footer implemented?
• Which Worker owns this endpoint?
• Which MCP tool wraps this API route?
• Which package exports this schema or helper?
• Which migrations shaped this data model?
• Which tests prove this route or component?

Useful generated entities:

• packages and workspaces;
• Svelte routes and layouts;
• Hono API routes;
• MCP tools and schemas;
• exported functions, types, and components;
• D1 migrations;
• Wrangler workers and custom domains;
• service bindings;
• tests and story metadata.

Codebook does not replace reading code. It shortens the path to the right file, symbol, route, or test.

Journal

Journal is the Wiki temporal memory projection of what happened.

It covers the "A broke, we saw B, did C and D, then it worked" class of knowledge without making every event a permanent architecture page.

Journal entries include:

• incidents and recoveries;
• troubleshooting reports;
• QA failures and release evidence;
• ops findings;
• migration notes;
• deploy notes;
• postmortems;
• follow-up tests or docs that should exist.

Journal entries should link back into Canon, Codebook, Atlas, QA queue evidence, Ops findings, and external evidence. Over time, repeated Journal patterns can be promoted into Canon or runbooks.

Librarian

Librarian is the chat/search assistant for the wiki.

It should be source-cited and budget-aware from day one. Semantic retrieval can come later, but the MVP should already use explicit links, frontmatter, full-text search, and graph neighborhoods before spending tokens.

Librarian should answer:

• What should I read next?
• What explains this term?
• Where did we decide this?
• Which runbook applies?
• Which implementation files are relevant?
• What is known, and what is still uncertain?

The first version can be retrieval-first rather than generative-first. A useful answer with citations is better than an impressive answer with weak provenance.

Cross-wiki and external references

CareerVector and JobCache should remain separate product wikis, but they must be able to refer to each other freely.

Do not solve this with special-case cross-product code. Treat every target as a reference URI. Internal pages, the other product's pages, code symbols, QA behaviours, ops incidents, Git commits, and external URLs all become graph edges with a target string and a resolved type when known.

Example target shapes:

wiki://careervector/architecture/QA-PLATFORM-DESIGN
wiki://jobcache/architecture/scraper-model
code://careervector/lib/admin-ui/src/components/PrivateFooter.svelte
qa://careervector/behaviour/P1-G6-S1
ops://careervector/incident/2026-05-19-footer-order
git://careervector/commit/532f1e80
https://developers.cloudflare.com/vectorize/platform/pricing/

Markdown should stay pleasant to write:

[[Canon]]
[[jobcache:Scraper Model]]
[[qa:P1-G6-S1]]
[Cloudflare Vectorize pricing](https://developers.cloudflare.com/vectorize/platform/pricing/)

The resolver normalizes these into graph edges. A missing target is still a valid edge; it becomes a broken-link or unresolved-link task for Atlas.

This keeps cross-wiki references and external references in the same model. There is no extra architecture for "the other wiki." It is just another namespace in the reference registry.

Graph integrity model

The wiki is not merely a set of documents with links. It should become the human-facing surface of a shared map of reality: a typed graph where each product owns one slice of the same system.

The model has nine canonical hub kinds. Wiki, QA, and Ops are projections over the same graph, not separate ontologies:

Wiki slice:
  rung 1: idea
  rung 2: implementation
  rung 3: journal

QA slice:
  rung 1: behaviour
  rung 2: suite
  rung 3: test

Ops slice:
  source: anomaly
  source: infra
  pool: event

The storage model is a graph, not a strict tree. Relationships are many-to-many by default. Product UIs project the graph into their own rungs so the model stays usable.

Shared vocabulary

Wiki, QA, Ops, Status, and JobCache must agree on graph wording. The vocabulary is not owned by the Wiki UI. It is a shared platform contract. Wiki may be the first polished surface, but the ontology is bigger than Wiki.

The shared package should therefore define the canonical primitive names, relation names, validation vocabulary, and Falkor projection helpers. Individual perspectives may add projection data, evidence views, action wrappers, and UI edges, but they must not add canonical Falkor node kinds outside the shared hub set.

Canonical hub wording:

idea
behaviour
implementation
suite
test
anomaly
infra
event
journal

Perspective names such as Wiki, QA, Ops, Status, JobCache, CareerVector, and shared are projections over the graph. They are not source annotation fields and they are not canonical node kinds.

idea is the graph primitive. Architecture, product vision, principles, and Canon pages are specializations or descriptions of ideas, not a separate tenth primitive unless we make that split explicitly later.

Required links

The QA spine is strict:

test -> suite -> behaviour -> idea

The implementation spine is also strict:

implementation -> behaviour
implementation -> idea
test -> implementation

Therefore a valid test must link to both:

• at least one suite;
• at least one implementation.

A valid suite must link to behaviour. A valid behaviour must link to idea or another idea-backed architecture claim. A valid implementation must link to at least one idea or behaviour. Missing links are not "documentation gaps"; they are graph integrity failures.

Suite and implementation are not the same level, and they do not need a direct semantic equivalence rule. A test bridges them because the test belongs to QA through its suite and touches Wiki through its implementation. Any surprising relationship between a suite's behaviours and a tested implementation is a signal to inspect, not automatically an invalid state.

Relationship registry

This registry is the current product contract. It separates conversation-level relationships from lower-level repo projections so implementation code does not smuggle in a new ontology.

Relationships are many-to-many unless a later section says otherwise. The stored direction is a canonical write direction only. Atlas, Librarian, QA, and Ops must support inverse traversal everywhere.

Core semantic relationships

These edges came directly from the wiki/QA/Ops model discussion.

An anomaly must satisfy at least one expectation edge: VIOLATES a behaviour or CHALLENGES an idea. It does not have to do both. This matters because some anomalies are "the system behaved as specified, but the product idea was wrong" and others are "the idea still holds, but the observed behaviour is wrong."

Two negative rules matter as much as the positive registry:

• There is no mandatory Suite -> Implementation edge. Suite and implementation are not the same level. A test bridges QA's suite tree and Wiki's implementation rung.
• There is no direct Test -> Behaviour semantic edge in the shared model. A behaviour's proof set is a suite, and the suite consists of tests. Historical importer evidence may mention behaviour-to-test links, but graph projection must normalize that provenance into suite membership instead of bypassing the suite rung.
• There is no direct Behaviour -> Infra edge. Behaviour does not care how it is realized. Reach infra through implementation, anomaly, or event paths.

QA projection contract

The QA layer now projects proof through explicit suites. Behaviour intent, suite membership, and concrete tests are separate rungs:

Suite VERIFIES Behaviour
Test BELONGS_TO Suite
Test CHECKS Implementation

Do not create a direct semantic Test -> Behaviour edge unless we deliberately revise the ontology later. If importer provenance exists, keep it as metadata on suite_behaviours or suite_tests, not as an ontology shortcut.

The current QA assets also show missing links clearly:

• story catalog rows already map well to Behaviour;
• story specs and proof files already map well to Test;
• QA does not yet know the Behaviour -> Idea links;
• QA does not yet know the Test -> Implementation links.

That is the point of the shared graph. It should make those missing links red instead of inventing low-confidence implementation surfaces or pretending the QA catalog already understands the whole product map.

Source and code projections

Pages, retrieval cards, code symbols, code paths, runs, and operator actions are source/provenance/API/UI projection data. They can describe, locate, cite, or act on the nine hub kinds, but they are not canonical Falkor node kinds.

Markdown pages back idea, behaviour, journal, and other hub claims. Retrieval cards back search over those sources. Code paths and symbols locate implementation evidence. Atlas, Canon, Codebook, Journal, Librarian, QA, and Ops should expose these details as projection fields or wrapper endpoints over the same graph.

The registry is intentionally stricter than a free-form wiki link graph. A hub node with a contractual label should satisfy that label's required edges. A Markdown page, retrieval card, code path, run, or operator action can discuss or support a hub without becoming that hub.

Validity and heat

Every graph object has a local validity contract. Every object checks whether its required links exist and whether connected objects satisfy their own local contracts.

Invalidity does not automatically propagate. Heat does.

red:    this object violates its own contract
orange: this object is connected to a red object or a hot neighborhood
green:  this object is locally valid and not near known invalidity

This produces useful hotspots. A broken test is red. Its suite, implementation, behaviour, and idea can be orange because they are affected, but they are not red unless their own required links are broken. The graph should make these failure modes obvious:

• a test with no suite;
• a test with no implementation;
• a suite with no behaviour;
• a behaviour with no idea or architecture;
• an implementation with no behaviour;
• an implementation with no idea or architecture;
• a connected object that is valid locally but adjacent to a red node.

Atlas should make this visible at map scale. The world view shows clustered hotspots; zooming in reveals the concrete node and missing link. Librarian should be able to answer why a node is red or orange and which links would make it valid.

Ops primitive: anomaly

Anomaly is the first Ops primitive.

An anomaly is a malevolent observation where reality diverges from what the map expected. It is not the general analytics product category and it is not the cloud-usage path. It covers user behaviour, system behaviour, product behaviour, data shape, workflow shape, adoption pattern, failure pattern, latency pattern, volume pattern, and idea/architecture reality.

The core anomaly expectation links are:

anomaly -> behaviour
and/or
anomaly -> idea / architecture

The rest of the graph is reached through existing mediated paths. These are query paths; the registry above remains the canonical write direction:

anomaly VIOLATES behaviour <- suite VERIFIES <- test BELONGS_TO
anomaly VIOLATES behaviour <- implementation REALIZES
anomaly CHALLENGES idea / architecture <- implementation IMPLEMENTS
test CHECKS implementation

An anomaly means the system's anticipation failed in a harmful or risky way. Benign emergence can be noted elsewhere, but it is not an anomaly in this Ops model.

Examples:

• expected behaviour, idea mismatch: users successfully use bulk flows, but the product idea was deliberate decision support and the observed pattern turns CareerVector into a bulk application launcher;
• behaviour mismatch, idea still plausible: users try to compare roles across workspaces, but the UI only supports per-workspace comparison even though the larger decision-support idea still wants that behaviour;
• system/data mismatch: the architecture assumed a typical workspace would add around 10 jobs, but observed median workspaces contain 100 jobs;
• QA-map mismatch: suites keep passing, but observed user paths show a behaviour nobody mapped or checked.

Anomaly can create an event when something happened that requires response or record. Journal then interprets that event:

anomaly RAISES event <- journal INTERPRETS

Event is separate from anomaly. Events can be expected or unexpected; anomaly is specifically about malevolent divergence from the expected behaviour or idea model.

Ops primitive: infra

Infra is the second Ops primitive.

Infra covers the internal and external operating substrate: Cloudflare, D1, R2, Vectorize, OpenAI, GitHub, Koyeb, private servers, runners, databases, queues, quotas, rate limits, capacity, billing envelopes, outages, and forecasts.

Infra is mostly forward-looking. It asks whether a resource, provider, or internal substrate will keep serving the project if we do nothing.

The core infra links are:

infra -> idea / architecture
infra -> implementation
infra -> event

Infra has no direct QA link. Behaviours, suites, and tests do not care how the behaviour is realized. QA is reached through mediated query paths:

infra SUPPORTS implementation <- test CHECKS
test BELONGS_TO suite VERIFIES behaviour
infra EXPLAINS anomaly VIOLATES behaviour

Infra can also explain anomalies:

infra -> anomaly

Examples:

• Cloudflare quota forecast says the wiki will not make it to month end;
• a private runner is running out of disk;
• a provider outage explains failed deploy events;
• unexpected viral usage creates an anomaly and also burns through quota, linking anomaly and infra.

Ops primitive: event

Event is the third Ops primitive.

An event is an occurrence that matters enough to record, react to, correlate, or aggregate. It can be expected or unexpected. Events are the Ops event pool.

The two main sources of events are:

anomaly -> event
infra -> event

Events can also link to implementation when a deploy, code path, migration, configuration, or runtime surface is involved:

event -> implementation

Journal is the wiki layer that laps up event clusters and turns them into sense-making support knowledge:

journal INTERPRETS event

One journal can aggregate many events, and one event can appear in more than one journal when it matters in multiple stories. Raw events answer what happened. Journal answers what it meant, what worked before, and what the next operator should try.

Examples:

• expected DDoS happened;
• deploy promoted a version;
• quota forecast crossed a warning threshold;
• provider outage started;
• provider outage ended;
• anomaly detected a harmful gap between observed behaviour and the expected behaviour or idea model;
• response action completed;
• verification signal confirmed recovery.

Support depth

The graph naturally creates support levels.

L1 support should be able to work mostly from Journal. Journal aggregates prior events and gives triage context: what happened before, what was tried, what worked, and what should be escalated.

L2 support needs Journal plus single implementations. They can inspect a concrete implementation and make a narrow fix when the problem is local.

L3 support needs the whole graph: Journal, Events, Infra, Anomalies, Implementations, Tests, Suites, Behaviours, and Ideas. They handle failures where a whole module or architecture assumption broke and the real fix requires rethinking the system, not patching a flesh wound.

MVP boundary

The MVP should not start with a heavy autonomous agent or constant RAG.

Start with:

• Markdown/frontmatter and inline source annotations;
• a scanner that compiles claims into the universal graph;
• FalkorDB materialization for traversal;
• scheduled/manual Git checkpoints;
• link parsing and graph edges;
• full-text search;
• Atlas graph plus book/chapter view;
• Codebook indexes for routes, packages, MCP tools, schemas, and components;
• Journal entries from humans, QA, and Ops;
• Librarian read/search with citations;
• MCP tools over the same API.

Delay:

• always-on semantic indexing;
• autonomous remediation;
• automatic canonical rewrites;
• R2-backed text storage;
• page-view writes;
• background polling.

Product test

The wiki is working when these questions are easy:

• "Why did we design it this way?"
• "Where is this implemented?"
• "What broke last time this failed?"
• "Which tests prove this behaviour?"
• "What should I read before changing this?"
• "What does JobCache know that CareerVector depends on?"

If the answer requires guessing across docs, code, QA, and Ops separately, the wiki has not yet become the glue.

Shared graph vocabulary

The wiki, the API graph projection, the inline @graph annotations in source, and the QA evidence index all speak the same dialect. That dialect is the shared graph vocabulary:

• Hub kinds. A small closed set: idea, behaviour, implementation, suite, test, anomaly, infra, event, and journal. Anything outside the set is rejected by the local validator before it can pollute the graph.
• Claim links. Artifact annotations group links by target hub kind. idea: [...] means "this artifact directly touches these ideas"; implementation: [...] means "this artifact directly touches these implementations", and so on. The graph builder derives the sanctioned edge relation from the source hub kind and target hub kind.
• Stable IDs. Node IDs are kebab-case, repo-global, and stable. A node is the same node regardless of which artifact mentions it; renaming an ID is a graph-wide refactor, not a local rename.
• Required-link rules. Some kinds carry "must link to" expectations. An idea is expected to be grounded by at least one owning Markdown or @graph block; an implementation is expected to point to the ideas it realises. Missing-required-link counts feed the Atlas weak-link list.
• Heat. Nodes inherit a derived heat number from in-bound link count, recency of references, and required-link health. Heat is part of the vocabulary so every consumer ranks consistently.

The vocabulary is the contract that lets the API, MCP, browser, agents, and this wiki argue about the same graph without translation layers.