Also written: caaat-harness, ca&at-harness, .c&at-harness, c@t-harness
Please be introduced to a cat who acquires things, for whatever purpose — maybe somebody knows.
Scope: the platform — skills, schemas, processes, the MCP server and the pipeline. Not what a folio IS (that is folio-assist-core), and not any folio’s own content, which lives in its own repository.
The graph an agent reads before it knows what this repository is.
Scope: phase one of two, and valid with NOTHING installed — no skills, no knowledge graph, no MCP, no work-plan store. One process here is the place to start. Everything else is composed on top of it, and nothing here may import from the layer above.
bootstrap, in the sourceOne process here is the place to start: processes/initialize-harness.bpmn.
A content-agnostic agent skills framework for authoring rigorous content with a
large language model — scientific papers and books, WHO SMART Guidelines, and
FHIR Implementation Guides — backed by an MCP server, role-based access control,
and a typed content-object model.
smart-trust: declares 1 graph(s) with no published viewer — ig-ast. Declared and not rendered is a gap, not a dead link.
smart-trust: 2 graph(s) hold materialized content and are READ-ONLY — fhir-artifact-index, openapi. Readable, not editable here: copy one out to your own folio/ to work on it. Separate from whether a viewer is published.
smart-immunizations: a viewer is published at /en/cat-harness/code/smart-immunizations/ by cat-harness’s code visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
smart-immunizations: has no docs/ of its own, so the tile opens its section of the landing (/#harness-smart-immunizations) rather than the instance’s own themed root.
The WHO SMART Guidelines base layer — the ingested WHO digital-health corpus, the methodologies read out of it, and the editorial voices derived from it.
smart-base: declares 1 graph(s) with no published viewer — themes. Declared and not rendered is a gap, not a dead link.
smart-base: 1 graph(s) hold materialized content and are READ-ONLY — fhir-artifact-index. Readable, not editable here: copy one out to your own folio/ to work on it. Separate from whether a viewer is published.
smart-base: a viewer is published at /en/cat-harness/attestations/smart-base/ by cat-harness’s attestations visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
who-iris: declares 1 graph(s) with no published viewer — themes. Declared and not rendered is a gap, not a dead link.
who-iris: 1 graph(s) hold materialized content and are READ-ONLY — catalogue. Readable, not editable here: copy one out to your own folio/ to work on it. Separate from whether a viewer is published.
Scientific source material used by folios that formalise mathematics, and the methodologies for formalising it in Lean that this layer adopts from that material.
folio-assistant-sci: 1 graph(s) render no viewer — lean — under a declared coverage.exempt.visualiser. Not a gap: This directory holds a Lean TEMPLATE, not a Lake package: there is nothing for doc-gen4 to elaborate, so there is no render to show. The visualiser the kind provides — the doc-gen4 render wrapped in the harness rail — belongs to a folio’s lean directory, where a package is built; README.md here documents how a folio declares it.
folio-assistant-sci: a viewer is published at /en/cat-harness/scenarios/folio-assistant-sci/ by cat-harness’s scenarios visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
The bare FHIR IG pipeline — SUSHI, the IG Publisher, Jekyll assembly and publication — with no WHO, DAK or SMART assumption. What a non-WHO implementation guide instantiates.
fhir-harness: a viewer is published at /en/cat-harness/schemas/fhir-harness/ by cat-harness’s schemas visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
fhir-harness: a viewer is published at /en/cat-harness/scenarios/fhir-harness/ by cat-harness’s scenarios visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
folio-assistant-core: a viewer is published at /en/cat-harness/uploads/folio-assistant-core/ by cat-harness’s uploads visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
folio-assistant-core: a viewer is published at /en/cat-harness/attestations/folio-assistant-core/ by cat-harness’s attestations visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
folio-assistant-core: a viewer is published at /en/cat-harness/scenarios/folio-assistant-core/ by cat-harness’s scenarios visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
folio-assistant-core: a viewer is published at /en/cat-harness/policies/folio-assistant-core/ by cat-harness’s policies visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
What implements the harness’s Tool definitions: the MCP servers, their tool registrars and routes. Definitions stay in cat-harness; this layer runs them.
cat-harness-tools: a viewer is published at /en/cat-harness/qa/cat-harness-tools/ by cat-harness’s qa visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
cat-harness-tools: has no docs/ of its own, so the tile opens its section of the landing (/#harness-cat-harness-tools) rather than the instance’s own themed root.
cat-harness: a viewer is published at /en/cat-harness/qa/cat-harness/ by cat-harness’s qa visualiser, which covers none of this instance’s directories. Declare one it covers and the tile links it.
The Zod source of bootstrap’s schemas, the generators that write bootstrap’s JSON Schemas, schema page and READMEs, and the checks bootstrap’s content must pass — runnable by an agent, with zod, liquidjs, Playwright and bpmn-js as its dependencies.
bootstrap-tools: declares 1 graph(s) with no published viewer — skills. Declared and not rendered is a gap, not a dead link.
bootstrap-tools: has no docs/ of its own, so the tile opens its section of the landing (/#harness-bootstrap-tools) rather than the instance’s own themed root.
bootstrap: 2 graph(s) render no viewer — models, skills — under a declared renderExemption. Not a gap: it owes Its own Knowledge Graph, written out as .jsonld with a .json copy and published at <base>/bootstrap/bootstrap.jsonld, the exact address its @id names. Governed by skills/bootstrap-graph-emission.md and skills/bootstrap-graph-publication.md.
bootstrap: has no docs/ of its own, so the tile opens its section of the landing (/#harness-bootstrap) rather than the instance’s own themed root.
Four things, in order
1. The work plan is where you say what you are doing.
Not a chat message, not a comment — beans, a committed
store any session or agent can read. Claim before you work so a sibling session
does not pick up the same item; a bean that turns out not to be wanted is
scrapped, with its reasons, never deleted.
cat-harness-tools/scripts/install-beans.sh &&export PATH="$HOME/.local/bin:$PATH"
beans list # what is open
beans create "<title>"# ...after checking the title does not exist
beans <id>--statusin-progress# claim it, visibly
2. Make your first folio. This repository is the platform; your content
lives in its own. One command scaffolds it — the manifests, the declaration, the
agent files and the link back here:
bun run cat init-folio --help
Then Get started walks the first block through validate,
render and review.
3. Know which kind of thing you are writing. A document is structured
prose; a paper is that plus the block kinds whose assertion is a formal claim,
backed by Lean and typeset through LaTeX. The choice decides which blocks are
legal and which gates run: Content types.
4. The documentation you will never read.All of it — the authoring guides, the architecture, the
publication workflow, the generated schema and skill reference. It is here, it
is thorough, and the honest expectation is that you will arrive at it from a
search engine at the exact moment something breaks. That is a fine way to use
it. The three steps above are the ones worth reading now.
When it is the machinery that has you puzzled rather than the authoring —
who does a thing, under which process, using which skill — start at
The platform. One sentence there
carries the whole model, and every word in it is a separately declared
object.
What is folio-assistant?
folio-assistant is the platform — it does not contain content. It provides
the skills, schemas, tooling, and an MCP (Model Context Protocol) server that an
LLM-driven agent uses to plan, author, validate, review, test, and publish a
folio of content that lives in a separate repository.
Separation of concerns. This documentation describes the formalism of the
framework and how to use folio-assistant — deliberately kept separate from
any specific content. Where content appears in these pages, it is purely
illustrative (an example), never the canonical artifact.
flowchart LR
A[Author + LLM] -->|chat / MCP tools| B(folio-assistant)
B --> C{Content adapter}
C -->|paper| D[Lean + LaTeX repo]
C -->|WHO SMART DAK| E[L2 BPMN / DMN / Excel]
C -->|WHO SMART IG| F[L3 FHIR / FSH]
B --> G[Skills + Schemas + RBAC]
D & E & F --> H[Published site / PDF / IG]
Supported content types
folio-assistant is pluggable — each content type is handled by a content
adapter and a matching skill package. The currently supported types:
The cross-cutting content-lifecycle
package (plan → author → validate → review → test → publish → feedback → retire)
applies to every content type. The
publication workflow models it properly — as BPMN
swimlanes, with the roles, the HCI validation gate, and the shared work plan.
Where to go next
Installation — prerequisites, clone, bun install, capability check.
Getting started — connect the MCP server to your LLM and run your first skill.
Content types — the formalism of each authoring domain.
Publication workflow — BPMN swimlane diagrams of the editing and publication processes: the HCI validation gate, who reviews what, and the shared work plan.
Agent onboarding — orientation for an LLM agent dropped into a folio: first steps, finding skills, the content-object model, QA sidecars.
Skills & roles — every skill and role, and how they work together with the LLM.
TypeScript API reference — the content-object model (Block, Chapter, Paper, builders, Zod constraints).
Architecture — adapters, MCP server, RBAC, the block model.
The Knowledge Graph — the subgraph taxonomy, which way the references run, and how repositories divide the work.
The Harness — instantiation, the dependency walk, and what harnessing a directory obliges.
Two Skills are worth reading before the pages above, because everything else
assumes them: getting-started
routes what you are actually trying to do, and
placement settles where a new
node belongs before you make one.
