folio-kb 0.1.0__tar.gz

folio_kb-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+_site/

folio_kb-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2026-10-04)
+
+The first release.
+
+- The `folio` command: create a library, write documents from genre skeletons, keep maps, the journal and comment threads, move and retire documents with links kept, search, serve and export a static site, and build and freeze papers.
+- The gate, `folio check`: links, genre cards, fields, placeholders, lifecycles checked against git, orphans, unique ids, current indices and stale quotes, with severities set in the charter.
+- Eight core genres: concept, note, entry, map, guide, project, journal, paper.
+- Two packs: knowledge-base (source, reading, survey; ingest and quiz) and lab (question, protocol, result, claim, report; record-a-result and write-a-report).
+- Seven skills: set-up, configure, write, organise, address, publish, run.
+- The shell: one stylesheet and one script for every page, in light and dark, with the library rail and a focus on one or more topics.
+- The documentation in `docs/`, itself a folio library, and the specification in `docs/spec/`.

folio_kb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piergiuseppe Mallozzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

folio_kb-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: folio-kb
+Version: 0.1.0
+Summary: A knowledge library a coding agent builds and keeps, checked by a gate.
+Project-URL: Homepage, https://github.com/pierg/folio
+Project-URL: Issues, https://github.com/pierg/folio/issues
+Project-URL: Documentation, https://pierg.github.io/folio/
+Author: Piergiuseppe Mallozzi
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: markdown-it-py
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# folio
+
+folio turns your coding agent into the librarian of a knowledge library: fast, good-looking HTML pages and Markdown records that live inside any project (lab notes, study notes, a project's docs) or stand on their own. Every document has one genre, and the genre fixes its job, its voice, its format and its checks. Documents link to each other like a Zettelkasten, and maps give a reader the way in.
+
+You do not run folio yourself. You install it by handing your agent a setup prompt, and from then on you ask in plain words: "add a concept for X", "tidy the maps", "go through my comments", "build the site". The agent follows folio's seven skills, calls the `folio` command, and runs the gate before every commit. folio is the method and the checks that keep an agent-written library honest and consistent, plus the shell that makes it pleasant to read.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pierg/folio/main/docs/assets/figures/how-folio-works-dark.svg">
+  <img alt="How folio works: you ask your agent in plain words; it picks one of folio's seven skills and writes typed, linked documents into the library in git, running folio check before each commit; folio serve renders the library as a site; a reader's comment is stored beside the page, and the address skill answers it and edits the page." src="https://raw.githubusercontent.com/pierg/folio/main/docs/assets/figures/how-folio-works-light.svg">
+</picture>
+
+## Install
+
+Paste this into your coding agent, in the project where the library should live:
+
+```text
+Install folio here: run `uv tool install folio-kb` (or `pipx install folio-kb`), then `folio init`, then read .agents/skills/set-up/SKILL.md and follow it.
+```
+
+The agent asks you at most three questions in one message (what the library is for, where it lives, which packs to switch on), creates the library and leaves the gate passing. A longer version of the prompt is in [SETUP.md](https://github.com/pierg/folio/blob/main/SETUP.md). folio needs Python 3.10 or later.
+
+## What a library looks like
+
+A library is a folder with a `folio.yaml`. It can be a project's `docs/`, a notes folder, or a whole repository.
+
+```
+docs/
+  folio.yaml            the charter: name, purpose, reader, packs, home maps
+  content/
+    index.html          the home page
+    concepts/<slug>/    one folder per genre
+    maps/
+    journal/2026/       one Markdown file per entry
+  assets/               figures, refs.bib, data
+  .folio/               generated indices, committed and checked
+.agents/skills/         the seven skills, at the project root
+```
+
+Each document keeps its facts in metadata and its prose in the body. The shell draws the header and the link panels from the metadata and the generated indices, so nothing is written twice.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pierg/folio/main/docs/assets/figures/anatomy-dark.svg">
+  <img alt="Anatomy of a document: the metadata in one file (genre, title, description, status, tags) becomes the page header; the body is shown as written; dates come from git; the cites, cited-by and journal panels come from the generated indices." src="https://raw.githubusercontent.com/pierg/folio/main/docs/assets/figures/anatomy-light.svg">
+</picture>
+
+Pages are plain HTML in git, readable with no build step. `folio serve` shows them locally with search, link previews, concept popovers, light and dark themes, and a comment panel; `folio export` writes a static site.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pierg/folio/main/docs/assets/figures/popover-dark.png">
+  <img alt="An entry in folio's shell, How corrections work, with the library rail on the left, the page panel on the right and a concept popover open over the link permanent record, showing that concept's definition." src="https://raw.githubusercontent.com/pierg/folio/main/docs/assets/figures/popover-light.png">
+</picture>
+
+Hover a link to preview the document it points to; hover a concept to read its definition without leaving the page. Readers can also comment on any rendered page, and the agent answers on the page itself.
+
+## Genres and packs
+
+| Where | Genres | For |
+| --- | --- | --- |
+| Core | concept, note, entry, map, guide, project, journal, paper | Any library: definitions, ideas, arguments, reading paths, tutorials, the state of some work, the dated record, LaTeX papers with frozen versions. |
+| knowledge-base pack | source, reading, survey | Keeping what you read: a verified citation with the original beside it, your close reading of it, and comparisons across works. Workflows: ingest, quiz. |
+| lab pack | question, protocol, result, claim, report | Work tested against evidence: ranked questions, protocols locked before they run, one home per measured number, claims, plain-English reports. Workflows: record-a-result, write-a-report. |
+
+A pack is switched on in the charter and rewrites nothing. A library can override a genre, add a variant for a second audience, or add genres, workflows and packs of its own.
+
+## The seven skills
+
+| Skill | Use it to |
+| --- | --- |
+| set-up | Create a library in a project or a new repository, write its charter, and leave the gate passing. |
+| configure | Change the charter: packs, home maps, a genre's limits, a new genre, a variant, a workflow. |
+| write | Add or revise any document in its genre's voice, link its concepts, flag what goes beyond its sources, put it on a map. |
+| organise | Move, merge, promote and retire documents and maps with every link, comment and date intact; run health passes. |
+| address | Answer the comments readers left on rendered pages, on the page they were left on. |
+| publish | Export the static site; build a paper and freeze versions of it. |
+| run | Follow a workflow from a pack or the library, step by step. |
+
+## The gate
+
+```bash
+folio check     # every problem in one pass; changes nothing; exit 0 only when there is no error
+```
+
+It runs offline, and CI runs the same command. It checks that every link resolves, every document meets its genre's card, no placeholder is left, records that must never change have not changed, nothing is orphaned, one fact keeps one home, and the generated indices are current.
+
+## Learn more
+
+- Documentation: [pierg.github.io/folio](https://pierg.github.io/folio/). It is itself a folio library, kept in [`docs/`](https://github.com/pierg/folio/blob/main/docs/), with a guide, the concepts, and a worked example from each pack.
+- The specification: [`docs/spec/`](https://github.com/pierg/folio/blob/main/docs/spec/). [`model.md`](https://github.com/pierg/folio/blob/main/docs/spec/model.md) is the contract the rest builds on; when anything disagrees with it, it wins.
+- Contributing: [CONTRIBUTING.md](https://github.com/pierg/folio/blob/main/CONTRIBUTING.md). Changes: [CHANGELOG.md](https://github.com/pierg/folio/blob/main/CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/pierg/folio/blob/main/LICENSE).

folio_kb-0.1.0/README.md

@@ -0,0 +1,93 @@
+# folio
+
+folio turns your coding agent into the librarian of a knowledge library: fast, good-looking HTML pages and Markdown records that live inside any project (lab notes, study notes, a project's docs) or stand on their own. Every document has one genre, and the genre fixes its job, its voice, its format and its checks. Documents link to each other like a Zettelkasten, and maps give a reader the way in.
+
+You do not run folio yourself. You install it by handing your agent a setup prompt, and from then on you ask in plain words: "add a concept for X", "tidy the maps", "go through my comments", "build the site". The agent follows folio's seven skills, calls the `folio` command, and runs the gate before every commit. folio is the method and the checks that keep an agent-written library honest and consistent, plus the shell that makes it pleasant to read.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/figures/how-folio-works-dark.svg">
+  <img alt="How folio works: you ask your agent in plain words; it picks one of folio's seven skills and writes typed, linked documents into the library in git, running folio check before each commit; folio serve renders the library as a site; a reader's comment is stored beside the page, and the address skill answers it and edits the page." src="docs/assets/figures/how-folio-works-light.svg">
+</picture>
+
+## Install
+
+Paste this into your coding agent, in the project where the library should live:
+
+```text
+Install folio here: run `uv tool install folio-kb` (or `pipx install folio-kb`), then `folio init`, then read .agents/skills/set-up/SKILL.md and follow it.
+```
+
+The agent asks you at most three questions in one message (what the library is for, where it lives, which packs to switch on), creates the library and leaves the gate passing. A longer version of the prompt is in [SETUP.md](SETUP.md). folio needs Python 3.10 or later.
+
+## What a library looks like
+
+A library is a folder with a `folio.yaml`. It can be a project's `docs/`, a notes folder, or a whole repository.
+
+```
+docs/
+  folio.yaml            the charter: name, purpose, reader, packs, home maps
+  content/
+    index.html          the home page
+    concepts/<slug>/    one folder per genre
+    maps/
+    journal/2026/       one Markdown file per entry
+  assets/               figures, refs.bib, data
+  .folio/               generated indices, committed and checked
+.agents/skills/         the seven skills, at the project root
+```
+
+Each document keeps its facts in metadata and its prose in the body. The shell draws the header and the link panels from the metadata and the generated indices, so nothing is written twice.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/figures/anatomy-dark.svg">
+  <img alt="Anatomy of a document: the metadata in one file (genre, title, description, status, tags) becomes the page header; the body is shown as written; dates come from git; the cites, cited-by and journal panels come from the generated indices." src="docs/assets/figures/anatomy-light.svg">
+</picture>
+
+Pages are plain HTML in git, readable with no build step. `folio serve` shows them locally with search, link previews, concept popovers, light and dark themes, and a comment panel; `folio export` writes a static site.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/figures/popover-dark.png">
+  <img alt="An entry in folio's shell, How corrections work, with the library rail on the left, the page panel on the right and a concept popover open over the link permanent record, showing that concept's definition." src="docs/assets/figures/popover-light.png">
+</picture>
+
+Hover a link to preview the document it points to; hover a concept to read its definition without leaving the page. Readers can also comment on any rendered page, and the agent answers on the page itself.
+
+## Genres and packs
+
+| Where | Genres | For |
+| --- | --- | --- |
+| Core | concept, note, entry, map, guide, project, journal, paper | Any library: definitions, ideas, arguments, reading paths, tutorials, the state of some work, the dated record, LaTeX papers with frozen versions. |
+| knowledge-base pack | source, reading, survey | Keeping what you read: a verified citation with the original beside it, your close reading of it, and comparisons across works. Workflows: ingest, quiz. |
+| lab pack | question, protocol, result, claim, report | Work tested against evidence: ranked questions, protocols locked before they run, one home per measured number, claims, plain-English reports. Workflows: record-a-result, write-a-report. |
+
+A pack is switched on in the charter and rewrites nothing. A library can override a genre, add a variant for a second audience, or add genres, workflows and packs of its own.
+
+## The seven skills
+
+| Skill | Use it to |
+| --- | --- |
+| set-up | Create a library in a project or a new repository, write its charter, and leave the gate passing. |
+| configure | Change the charter: packs, home maps, a genre's limits, a new genre, a variant, a workflow. |
+| write | Add or revise any document in its genre's voice, link its concepts, flag what goes beyond its sources, put it on a map. |
+| organise | Move, merge, promote and retire documents and maps with every link, comment and date intact; run health passes. |
+| address | Answer the comments readers left on rendered pages, on the page they were left on. |
+| publish | Export the static site; build a paper and freeze versions of it. |
+| run | Follow a workflow from a pack or the library, step by step. |
+
+## The gate
+
+```bash
+folio check     # every problem in one pass; changes nothing; exit 0 only when there is no error
+```
+
+It runs offline, and CI runs the same command. It checks that every link resolves, every document meets its genre's card, no placeholder is left, records that must never change have not changed, nothing is orphaned, one fact keeps one home, and the generated indices are current.
+
+## Learn more
+
+- Documentation: [pierg.github.io/folio](https://pierg.github.io/folio/). It is itself a folio library, kept in [`docs/`](docs/), with a guide, the concepts, and a worked example from each pack.
+- The specification: [`docs/spec/`](docs/spec/). [`model.md`](docs/spec/model.md) is the contract the rest builds on; when anything disagrees with it, it wins.
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

folio_kb-0.1.0/craft/README.md

@@ -0,0 +1,10 @@
+# Craft
+
+How to show something on a page so the reader sees it at once. Each file is short and covers one kind of thing. The components and tokens they use are in `shell/COMPONENTS.md`.
+
+- [`layout.md`](layout.md): the reading column, and when a page may go wider.
+- [`figures.md`](figures.md): when a figure earns its place, and how to make one.
+- [`tables.md`](tables.md): tables that compare, and how to keep them readable.
+- [`diagrams.md`](diagrams.md): drawing a mechanism as inline SVG that works in both themes.
+
+The rule behind all four: show the one thing the reader needs, in the plainest form that shows it, and say in the caption what to look at.

folio_kb-0.1.0/craft/diagrams.md

@@ -0,0 +1,43 @@
+# Diagrams
+
+A diagram shows how something works: the parts, and what moves between them. It is worth drawing when the reader would otherwise hold four or more parts in their head at once.
+
+## Draw the real mechanism
+
+- Name the parts as the text names them. A box called "Processor" in a page about "the softmax step" is a second vocabulary.
+- Show what flows, and which way. Arrows carry one meaning per diagram: data, or control, or time, never a mix.
+- Leave out what the point does not need. A diagram of everything shows nothing.
+- If the order matters, number the steps and use the same numbers in the text.
+
+## Inline SVG in both themes
+
+Write the SVG inside the page so it can use the shell's tokens:
+
+```html
+<figure>
+<svg viewBox="0 0 320 80" role="img" aria-label="A row of scores goes through the softmax and comes out as weights">
+  <g style="fill: none; stroke: var(--ink-2); stroke-width: 1.5">
+    <rect x="10" y="25" width="80" height="30" rx="4"/>
+    <rect x="230" y="25" width="80" height="30" rx="4"/>
+    <path d="M90 40 H230" marker-end="url(#arrow)"/>
+  </g>
+  <g style="fill: var(--ink); font: 12px var(--sans)" text-anchor="middle">
+    <text x="50" y="44">scores</text>
+    <text x="270" y="44">weights</text>
+  </g>
+  <defs><marker id="arrow" viewBox="0 0 8 8" refX="8" refY="4" markerWidth="8" markerHeight="8" orient="auto">
+    <path d="M0 0 L8 4 L0 8 z" style="fill: var(--ink-2)"/></marker></defs>
+</svg>
+<figcaption>The softmax turns each row of scores into weights that sum to one.</figcaption>
+</figure>
+```
+
+- Fill and stroke come from tokens (`var(--ink)`, `var(--ink-2)`, `var(--rule)`, `var(--accent)`), set in `style`, never from hex values. A token works in `style`, not in a plain `fill=` attribute.
+- Use the accent for the one part the caption names. Everything else is ink or rule.
+- Text is at least 12 units at the `viewBox` width, so it stays legible on a phone.
+- Give the SVG `role="img"` and an `aria-label` that says what it shows.
+- Keep a `viewBox` and no fixed width, so it scales to the column.
+
+## Before you keep it
+
+Look at it at phone width and in dark mode. If a label is too small or a line disappears, fix the drawing, not the page.

folio_kb-0.1.0/craft/figures.md

@@ -0,0 +1,38 @@
+# Figures
+
+## When a figure earns its place
+
+Draw a figure when the reader must see a shape: a trend, a comparison of sizes, a structure, the steps of a process. If one sentence says it as well, write the sentence.
+
+Each figure makes one point. Write that point first, as the caption. If you cannot write it in one sentence, the figure is doing two jobs: make two figures.
+
+## Where it lives
+
+- The source and the rendered file go in `assets/figures/`. Link it from the root: `/assets/figures/<name>.svg`.
+- Prefer SVG. Use PNG only for photographs or screenshots.
+- A paper, a report and a page that show the same result reuse the same file. Never copy it.
+
+## The markup
+
+```html
+<figure>
+<img src="/assets/figures/attention-tiling.svg" alt="Queries are scored against one tile of keys at a time, and the running softmax is rescaled after each tile">
+<figcaption>Each new tile rescales the running sum before adding to it.</figcaption>
+</figure>
+```
+
+- `alt` says what the figure shows, for a reader who cannot see it.
+- The caption says what to look at, not what the figure is. "Each new tile rescales the running sum" beats "Diagram of FlashAttention tiling".
+- A number in a caption cites its source, like any number on the page.
+
+## Charts
+
+- Pick the form by the question. Change over time: a line. Comparing a few amounts: bars from zero. Parts of a whole: a single stacked bar, not a pie.
+- Label lines and bars directly, at their ends. Avoid a legend the eye must travel to.
+- Keep to two or three colours, from the tokens. Grey for context, the accent for the thing the caption names.
+- Start a bar's axis at zero. Say when a line's axis does not.
+- Remove what does not carry data: heavy grids, borders, shadows, 3D.
+
+## Both themes
+
+An SVG that hard-codes black text vanishes in dark mode. Use `currentColor` for text and lines, or inline the SVG and use the shell's tokens (see `diagrams.md`). A PNG needs a background that reads on both, or a transparent one tested on both.

folio_kb-0.1.0/craft/layout.md

@@ -0,0 +1,32 @@
+# Layout
+
+## The reading column
+
+Prose sits in one column about 68 characters wide (`--measure`). That width is easy to read and is the same on every page. Do not set widths on paragraphs, and do not put prose side by side.
+
+On a wide screen the page panel sits to the right of the column. On a narrow screen it follows the page. Nothing a page writes goes in the panel.
+
+## Order
+
+- The body starts with content. The shell has already drawn the title, the description and the metadata.
+- Use `<h2>` for the parts of the argument and `<h3>` for small labelled parts inside one. Never skip to `<h4>` for size. The outline is built from `<h2>` and `<h3>`.
+- One idea per section. If a section needs two headings inside it, it is two sections.
+- Put a check-yourself at the end of the section it tests, not at the end of the page.
+
+## Going wider
+
+A table, a figure or a code block may need more than the column. It keeps to the column, and scrolls sideways inside its own box on a small screen. The page itself never scrolls sideways.
+
+If a figure only reads at a larger size, link the full-size file from the caption rather than stretching the page.
+
+## Phones
+
+Check every page at phone width. Watch for:
+
+- long words or paths that do not wrap (wrap them in `<code>`; the shell lets code break);
+- tables with more than four columns (split them, or turn them around so rows are the long side);
+- figures with small text (redraw them with fewer, larger labels).
+
+## Space
+
+Leave space to the shell. Do not add `<br>` or empty paragraphs to push things apart, and do not set margins inline. If something looks cramped, the structure is usually wrong: a list written as a paragraph, or two ideas in one section.

folio_kb-0.1.0/craft/tables.md

@@ -0,0 +1,34 @@
+# Tables
+
+## When to use one
+
+Use a table when the reader compares the same few facts across several things. Each row is a thing; each column is one fact about it. If there is one fact per thing, use a list. If there are two things, write a sentence.
+
+## Shape
+
+- Put the things down the side and the facts across the top. A table with many rows and few columns reads on a phone; the reverse does not.
+- Keep to about five columns. Split a wider table into two that each answer one question.
+- Order the rows by what matters most to the reader, not alphabetically, unless the reader will look a row up by name.
+- The first column names the row. In a survey, it links the source.
+
+## Cells
+
+- Numbers: same unit and precision down a column, unit in the header, not in each cell. Right-align them with `class="num"`.
+- Empty is not the same as zero. Write "not reported" or use `<span class="not-measured">` for what was not measured.
+- Keep cells short: a fact, not a sentence. A cell that needs a sentence is a footnote under the table.
+- Every number cites its source in the same row, as the gate asks.
+
+## Markup
+
+```html
+<table class="compare">
+<thead>
+<tr><th>Work</th><th class="num">Year</th><th>Exact attention</th></tr>
+</thead>
+<tbody>
+<tr><td><a href="/content/sources/2017-attention-is-all-you-need/">Attention Is All You Need</a></td><td class="num">2017</td><td>yes</td></tr>
+</tbody>
+</table>
+```
+
+Use `<thead>` and `<th>`. A `<caption>` may say what to read across. Do not style a table inline: the shell sets the rules, the spacing and the scrolling on a small screen.

folio_kb-0.1.0/genres/concept/GENRE.md

@@ -0,0 +1,78 @@
+---
+name: concept
+format: html
+path: content/concepts/{slug}/index.html
+id: slug
+skeleton: skeleton.html
+lives: revised
+states: [draft, live, historical, retired]
+checks:
+  require: [defn]
+  forbid: [h2]
+  max_words: 250
+  cites: { defn: none }
+  defined_once: true
+on_map: optional
+---
+
+# Concept
+
+A concept defines one term, once, so that every other document can link to it instead of explaining it again.
+
+## Reader
+
+Someone who met the term on another page and wants it pinned down. Often they read only the definition, in the popover that shows when they hover a link. They have no context beyond that definition.
+
+## Voice
+
+Impersonal, present tense, timeless. No "we", no "I", no story of how the term came about. The definition stays true when any result or number changes.
+
+> The softmax turns a row of scores into weights that are positive and sum to one.
+
+## Metadata
+
+No fields beyond the core. The `title` is the term, as a reader would search for it. The `description` says in one sentence what the concept is for. It is not the definition: the definition lives in the `defn`.
+
+## Shape
+
+The shell draws the term and the description above the body. The body starts with the definition.
+
+1. `defn`: a `<blockquote class="defn" id="{slug}">`. It opens with `<span class="defn-name">` holding the term alone. Then one to three sentences follow. This is the sentence other pages cite and the popover shows. Every symbol in it is named in it or is a `defn-link`.
+2. A figure, optional. One `<figure>` that makes the idea obvious, with a `<figcaption>` that says what to see. A figure other documents also use comes from `assets/figures/`.
+3. Short sections, optional, each under an `<h3>`. "Why it matters" takes two to four sentences. "The trap" names the usual misreading. "Related" links neighbouring concepts in a sentence or two.
+
+## Forbidden
+
+- An `<h2>` section. A concept that needs sections is an entry. Caught by `forbid: [h2]`.
+- More than 250 words. Caught by `max_words`.
+- A citation inside the definition. Caught by `cites: { defn: none }`, which applies to the `defn` only. Sources and results may be cited below it.
+- A second definition of the same term. Caught by `defined_once`: no other document carries a `defn` with the same `defn-name`.
+- A prose re-explanation of the term on another page. Judged, not checked.
+- A label after the term in `defn-name`, such as "Softmax, definition". Judged, not checked.
+- A concept for a part of one particular system. That stays as prose in its entry. Judged, not checked.
+
+## Steps
+
+- Search before writing: `folio search <term>`. If the term is defined, link to it or revise it. Never add a second one.
+- A concept earns its page when the idea is transferable, not trivial, and needed on at least two documents. Judged, not checked. The organise skill folds a thin concept into its entry with `folio rm --to`.
+- After writing it, replace every other explanation of the term with `<a class="defn-link" href="/content/concepts/{slug}/">`. The write skill does this sweep.
+- Delete the optional parts you do not use. A placeholder left in the page is reported by the gate.
+- An invented example or figure gets a flag, because the source did not say it.
+
+## Lifecycle
+
+Revised in place. The slug is the id and never changes; a move uses `folio mv`. A concept is born when a term needs explaining a second time, often out of a note or an entry's section. It becomes `historical` when the library stops using the term. It becomes `retired` when merged into another concept with `folio rm --to`. If it outgrows 250 words, the long form moves into an entry and the concept stays short.
+
+## Example
+
+```html
+<meta name="title" content="Softmax">
+<meta name="description" content="The function that turns attention scores into weights.">
+<!-- body -->
+<blockquote class="defn" id="softmax">
+<span class="defn-name">Softmax</span><br>
+The softmax of a vector of scores is the exponential of each score divided by the sum of the exponentials of all of them.
+</blockquote>
+<h3>The trap</h3>
+<p>Computed as written, the exponentials overflow for large scores. Adding the same constant to every score leaves the result unchanged, so implementations subtract the maximum first.</p>
+```

folio_kb-0.1.0/genres/concept/skeleton.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{term}}</title>
+<meta name="genre" content="{genre}">
+<meta name="title" content="{{term}}">
+<meta name="description" content="{{one sentence: what this concept is for}}">
+<meta name="tags" content="{{tags}}">
+<link rel="stylesheet" href="/shell/folio.css">
+<script src="/shell/folio.js" defer></script>
+</head>
+<body>
+<main>
+
+<blockquote class="defn" id="{slug}">
+<span class="defn-name">{{term}}</span><br>
+{{one to three sentences that define the term; no citations; every symbol named here}}
+</blockquote>
+
+<figure>
+{{optional: one figure that makes the idea obvious}}
+<figcaption>{{what the reader should see}}</figcaption>
+</figure>
+
+<h3>Why it matters</h3>
+<p>{{two to four sentences: what the concept buys, and where it is used}}</p>
+
+<h3>The trap</h3>
+<p>{{the usual misreading, named precisely}}</p>
+
+<h3>Related</h3>
+<p>{{how it sits next to}} <a class="defn-link" href="{{link to a neighbouring concept}}">{{neighbour}}</a>.</p>
+
+</main>
+</body>
+</html>

folio_kb-0.1.0/genres/entry/GENRE.md

@@ -0,0 +1,75 @@
+---
+name: entry
+format: html
+path: content/entries/{slug}/index.html
+id: slug
+skeleton: skeleton.html
+lives: revised
+states: [draft, live, historical, retired]
+checks:
+  require: [thesis, h2]
+  cites: any
+on_map: required
+---
+
+# Entry
+
+An entry explains or analyses one subject in depth, takes a position on it, and cites what each claim rests on.
+
+## Reader
+
+Interested and capable, but not an expert in this subject. They will read for several minutes and want to navigate by section.
+
+## Voice
+
+Analytical. It takes a position and supports it. Each claim cites what it rests on, where the claim is made: a source, a result, a concept, another entry. Uncertainty is stated once, precisely, never spread as hedging.
+
+> Every token scores against every other token, so doubling the context quadruples the scores.
+
+## Metadata
+
+No fields beyond the core. The `title` is the subject. The `description` says in one sentence what the entry covers, and for whom.
+
+## Shape
+
+The shell draws the title and description above the body, and the generated panels list what the entry cites and what cites it. So the body has no list of what it rests on.
+
+1. `thesis`: a `<p class="thesis">` that opens the body. It states the entry's position in one to three sentences.
+2. `h2`: sections, each under an `<h2 id="...">`. The sections carry the argument, one step each. A figure goes where it carries a step.
+3. Check-yourself, optional: `<details class="check"><summary>question</summary><div class="ans">answer</div></details>` at the end of a section.
+
+Files only this entry uses, such as a source's full text, may sit beside `index.html` in its folder. A figure other documents also use lives in `assets/figures/`.
+
+## Forbidden
+
+- A wall of prose with no sections. Caught by `require: [h2]`.
+- An entry that cites nothing. Caught by `cites: any`, which needs at least one resolving citation.
+- A closing "What this rests on" list. The generated panel shows what the entry cites. Judged, not checked.
+- A missing statement of position. Caught by `require: [thesis]`. Whether it is a real position is judged, not checked.
+- A claim with no support where it is made. Judged, not checked.
+- A definition written out again when a concept holds it. A second `defn` is caught by `defined_once`, which compares every `defn` in the library. A prose re-explanation is judged, not checked. Link the concept instead.
+- A number restated as the entry's own when another document holds it. Judged, not checked; a pack can make it a check.
+
+## Steps
+
+- Before writing, list the concepts the subject needs. Link each with `class="defn-link"`. A term the entry must define, and another page also needs, becomes a concept first.
+- Write the thesis last, then move it to the top. It must match where the sections actually land.
+- Anything the sources did not say (an example, a framing, a claim from general knowledge) gets a flag.
+- Add the entry to at least one map: `folio map add <map> <doc>`. Give a `--reason` only when it says more than the description.
+
+## Lifecycle
+
+Revised in place, and the most revised genre. A note that grew sections is promoted into an entry. An entry that has become a teaching sequence is split into a guide, with the entry left as the reference or retired into it. An entry overtaken by a better one is `retired` into it with `folio rm --to`. One that was true of its time is `historical`, with its description saying when.
+
+## Example
+
+```html
+<meta name="title" content="Why attention is quadratic">
+<meta name="description" content="Where the n-squared cost of self-attention comes from, for someone who knows matrix products well.">
+<!-- body -->
+<p class="thesis">Every token scores against every other token. A sequence of n tokens makes n squared scores, so the cost grows with the square of the context.</p>
+<h2 id="scores">Where the scores come from</h2>
+<p>The product of the queries and the transposed keys is an n-by-n matrix ...</p>
+<h2 id="memory">What tiling changes, and what it does not</h2>
+<p>Each row of scores goes through a <a class="defn-link" href="/content/concepts/softmax/">softmax</a>, which tiling can compute without storing the matrix ...</p>
+```

folio_kb-0.1.0/genres/entry/skeleton.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{title}}</title>
+<meta name="genre" content="{genre}">
+<meta name="title" content="{{title}}">
+<meta name="description" content="{{one sentence: what this entry covers, and for whom}}">
+<meta name="tags" content="{{tags}}">
+<link rel="stylesheet" href="/shell/folio.css">
+<script src="/shell/folio.js" defer></script>
+</head>
+<body>
+<main>
+
+<p class="thesis">{{the entry's position, in one to three sentences}}</p>
+
+<h2 id="{{section-id}}">{{first step of the argument}}</h2>
+<p>{{the argument, each claim citing what it rests on, and each term linked to its}} <a class="defn-link" href="{{link to a concept}}">{{concept}}</a>.</p>
+
+<details class="check">
+<summary>{{a question the reader should now be able to answer}}</summary>
+<div class="ans">{{the answer}}</div>
+</details>
+
+</main>
+</body>
+</html>