What the workspace knows

A desk is one task and goes away with it. A conversation is shorter still. So an instance keeps one thing that outlives both, and it is a directory you can open: knowledge/, in the instance directory, one Markdown note per topic, written and edited by every session with the file tools it already has.

the note · index and validate · the common note · who writes here

A directory, not a thing behind a tool

A fresh instance has knowledge/ and nothing in it. It fills with notes, and a note is a file: readable with cat, searchable with grep, editable with the same tools a session uses on any other file, and yours to copy out of the instance whenever you want it somewhere else. The instance's Claude Code home turns the built-in memory off, so this directory and your customization files are what outlives a conversation.

<instance>/knowledge/
  common.md              handed to every session at its start
  deployment.md          one topic
  the-payments-api.md    one topic
  who-runs-the-build.md  one topic
  files/                 what a note needs of its own: a template, an image

The one directory knowledge/ holds is files/: the files a note needs of its own, in whatever layout and format suits them. None of it is a note, so index and validate pass it over. Any other directory is reported the way a stray file is, since nothing here would ever look in it.

Facts only. A note says what is true and where that came from; what the team is held to is customization, in your words, where you can read it. The one test is the same one that sorts any line: a line that can be obeyed or broken belongs in customization, and a line that is true or false belongs here.

The note

A note opens with four fields and nothing else, then the body, which is ordinary Markdown.

---
summary: How this instance is deployed, and who may press it
tags: [deployment, release, ci]
sources: [projects/shop/deploy.sh, https://example.com/runbook, <user>]
updated: 2026-09-18
---

The build runs on…

field	what
`summary`	one line: what the note is about, for somebody deciding whether to open it
`tags`	at least three, lowercase and hyphenated, no duplicates; they are what a search matches on, so they are a decision the writer makes rather than a word that happens to be in the text
`sources`	where it came from: a path from the instance directory, a URL, or `<user>` when you said it; never a path under `desks/` or `archive/`, since a desk is filed away when its seat retires and what is filed away is history — what a note needs from a desk is copied into the note, or under `knowledge/files/`
`updated`	the date it last changed, and never a date in the future

The head is those four fields and nothing else, and the filename is lowercase and hyphenated like the tags. That is the whole contract, and validate is what reads it back.

There is no id, no status and no expiry, because there is nothing for them to do: a note that is wrong is edited, and a note that is dead is deleted. One topic per file. A note that has grown two topics is two files.

index and validate

Two tools are served over the directory, and neither keeps anything of its own: both are built from the files every time they are called, so a note changed a moment ago is the note the next call sees. Both go to every seat.

call	what it answers
`index()`	the header: how many notes there are, when the directory last changed, every tag with its count, and any file it could not read
`index(tags)`	the notes carrying a tag, the ones carrying more of what was asked first
`validate`	the whole directory against the rules above, one line per problem, each saying the rule it breaks

index matches on tags and never on filenames or summaries. That is the point of it: a search means what somebody decided when they wrote the note, and words are what grep is for. A session looking for a phrase greps the directory like any other; a session looking for a subject asks for the tag.

validate answers with the rule each problem breaks, so a session fixes what it wrote without going to find the contract. The reference has both with their arguments.

The common note

One note is the framework's business. knowledge/common.md is handed to every session at its start, after your customization files, in a frame that names it:

<knowledge source="knowledge/common.md">
---
summary: What everybody here needs on their first turn
…
</knowledge>

It is an ordinary note otherwise, and it is the Leader's to gather: the team, the business, the lingo, where things are, and which notes a newcomer reads first. Because it is handed to everybody, the instance is born asking before it changes — Edit(/knowledge/common.md) is in the ask list, so a session that would rewrite that one file stops for your press while the rest of the directory stays open to write. A permission popup never offers that one-file rule as Always; the Leader settles it with permission when you say so. No file, no frame, no error: a workspace that has learnt nothing yet reads exactly as an empty one does.

A change to it reaches the sessions started after it and no others. When something has to reach a session that is already running, tell it in words, or restart it: restart_worker for a Worker.

Who writes here

Every seat. Edit(/knowledge/**) is one of the rules a fresh instance is born with, so a Worker that has just measured something writes it down where it found it out, without asking anybody and without a tool of its own. The Leader's part is not a gate on the directory; it is the common note, and knowing what is in the rest.

What belongs here is what somebody would otherwise have to find out twice: the measurement and what it was measured on, the trap and what it cost, where a thing lives. What does not belong here is anything that is true only of one round — that goes on a desk, which is what a desk is for.

Next

Customization: the three files that say what this team is held to, and every key of openovai.json.