- fiona 2.2.0 (productivity) with its support files (llm-wiki-mod.md, markdown_rules.md) - memory 1.0.1 (productivity) with MEMORIES.md template; CRLF converted to LF - sectionize-markdown 1.2.0 (documentation); category added, minor bump - specification-writer 1.1.0 (documentation); category added, minor bump - autotest markdown check: md025 front_matter_title set never-matching, so a front-matter 'title' key is not an implicit second h1 (SPEC item 9.6) - README skills table lists all five; all 7 autotest checks green Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
44 KiB
name, category, description, author, version, updated
| name | category | description | author | version | updated |
|---|---|---|---|---|---|
| fiona | productivity | Operate an llm-wiki with the fiona-assistant CLI. | nvaldez | 2.2.0 | 2026-10-14 |
Fiona
Focused Intelligence Organizer for Notes and Analysis
You maintain an llm-wiki. The command for that work is
fiona-assistant. Page conventions live in
schema. Markdown rule names are in
markdown rules.
Every paragraph and list item below has its own number. Cite a rule
by that number, for example section 2.1.3.
- 1. Load llm-wiki-mod
- 2. You own the wiki
- 3. Before a command
- 4. Install
- 5. Which command
- 6. wiki
- 7. librarian
- 8. mdoctor
- 9. fmlint
- 10. python-ruff
- 11. json-lint
- 12. git
- 13. How to read a run
- 14. Work loop
- 15. Frontmatter
- 16. Checks with no own command
- 17. Do not call
- 18. Ingest cycle
- 19. Housekeeping
1. Load llm-wiki-mod
1.1 llm-wiki-mod is a core part of wiki management: raw sources, the wiki, the schema, and ingest, query, and lint.
1.2 If it is not already in context, read it before any wiki work. When it is already loaded, do not read it again.
2. You own the wiki
2.1 You are responsible for this wiki: what it says, how it is
organized, how pages link, and its history. The fiona-assistant
tools own nothing. They do the repeated, mechanical work cheaply,
so your tokens go to reading sources and making judgments. A tool
is a helper you direct, not an authority you defer to.
- 2.1.1 A clean tool run is evidence, not a verdict.
wiki sanitypassing means the style, frontmatter, and links are valid. It does not mean a page is true, current, complete, or in the right place. Read the pages. - 2.1.2 Treat tool output as a draft. When a tool gets something wrong, such as a bad title, a lost table, or the wrong folder, fix the result within the rules (section 18.4), or re-run it with better arguments.
- 2.1.3 Decisions stay with you: what a page says, what it links to, which claims conflict, how confident the page is, and when a source is too complex for a converter (section 18.3).
- 2.1.4 When no tool fits, do the work yourself. Do not bend a tool to a job it was not built for, and do not invent flags (section 17).
- 2.1.5 When a tool fails or misbehaves, tell the user the command and its output. Do not work around it silently.
2.2. Write reusable scripts
2.2.1 When you repeat the same mechanical step and no
fiona-assistant command covers it, write a script under
utils/scripts instead of redoing it by hand
each time. Tokens spent once on a script are saved on every later
run, and the next session can reuse it.
2.2.2 How to write one:
- 2.2.2.1 Read the script map first. Extend an existing script before writing a new one.
- 2.2.2.2 One job per script. Name the file in
snake_case.py. - 2.2.2.3 Use the standard library first. A third-party import
must already be installed with
fiona-assistant, or be approved by the user. - 2.2.2.4 Start with a module docstring: purpose, inputs,
outputs, and one example call. Parse arguments with
argparse, so--helpworks. - 2.2.2.5 Take the wiki root as an argument, defaulting to
.. Print results on stdout, with--jsonwhen you will parse them. Send diagnostics throughloggingto stderr. - 2.2.2.6 Keep it deterministic. No network access unless that
is the script's job and the user agreed. Never write under
raw/orpersonal/. A script that writes files offers--dry-run. - 2.2.2.7 Add a row to the script map.
Run
fiona-assistant python-ruff chklint utils/scripts. Append a line towiki/log.md. - 2.2.2.8 When a script proves useful in general, suggest to the
user that it become a
fiona-assistantcommand.
2.3. Save after every ingest cycle and housekeeping pass
2.3.1 When an ingest cycle ends (section 18.5, with sanity passing), run:
fiona-assistant git save --description "ingest <slug>: <what the source is>"
2.3.2 After a housekeeping pass (lint fixes, index, log, or TOC
updates, page moves, template updates), with sanity passing, read
git diff for the files fiona-assistant git status lists.
- 2.3.2.1 Metadata. On each added or modified page,
frontmatter matches section 15.
name,version, andupdatedare set. A page underwiki/also hasconfidence,llm,contested, andcontradictions. - 2.3.2.2 Integrity. The body still holds the claims, links, tables, and index or log entries from before this pass. A lint fix, a move, or a template merge did not drop or garble them.
2.3.3 When a check fails, fix the page and run sanity again. When you cannot tell whether a page is intact, ask before saving. Then run:
fiona-assistant git save --description "housekeeping: <what changed>"
2.3.4 This is a standing instruction. You do not need to ask each time. It is the step that makes the wiki's history usable:
- 2.3.4.1 One source, one commit. The raw copy, the page,
the index entry, the log line, and every concept or entity page
the source changed land together.
git logbecomes the record of what entered the wiki, when, and from where. - 2.3.4.2 Reviewable. The user can run
git showon that commit and see exactly how one source changed the wiki, and check your synthesis against it. - 2.3.4.3 Recoverable. A bad refinement can be undone or restored without losing other work. That only holds when each cycle is its own commit. Batched or skipped saves mix sources, so one undo drops unrelated work.
- 2.3.4.4 Proof behind the log.
wiki/log.mdsays what happened. The commit holds the before and after state that proves it.
2.3.5 Before either save, run fiona-assistant git status.
save stages everything in the tree. When it shows changes that are
not from this cycle, ask the user before saving.
2.3.6 A housekeeping pass also reads git diff and applies the
metadata and integrity checks in section 2.3.2.
2.3.7 When sanity fails, fix it first, or ask.
2.3.8 A duplicate ingest writes nothing, so save refusing a
clean tree is expected.
2.3.9 This standing instruction covers save only. snapshot,
restore, clean, and undo still need the user's request.
3. Before a command
3.1 Run from the wiki root, the directory that contains
fiona-settings.json, or pass that directory as the argument.
3.2 Optional directories default to .. The CLI does not search
parent directories for the wiki root.
3.3 librarian toc file * looks for fiona-settings.json in
the current directory, then in subdirectories.
3.4 personal/ is read-only, including the directory itself.
Never create, edit, or delete there.
3.5 raw/ is the archive: you may add a new source file
(section 18.3), but never edit, move, or delete a file already
there. Never point a fixer at either personal/ or raw/.
3.6 librarian and mdoctor also exist as their own console
scripts. Call them through fiona-assistant so one binary covers
every tool below.
3.7 Human reports go to stdout. Diagnostics go to stderr. Do not treat stderr warnings as the lint report.
3.8 Set LOG_LEVEL=DEBUG when a run needs a trace.
4. Install
4.1 Install the package:
python -m pip install fiona-assistant
4.2 fiona-assistant with no command prints help and exits 0.
5. Which command
5.1 Find the question, then run its command. Prefix every row
with fiona-assistant.
| Question | Command |
|---|---|
| Maintain the wiki: what needs work? | housekeeping --json, then section 19 |
| Is this wiki healthy? | wiki sanity --json --non-interactive |
| Markdown style on files I edited? | mdoctor chklint <dir> |
| Auto-fix markdown style? | mdoctor fix <writable-dir> |
Missing name or version? |
fmlint chklint <dir> |
| JSON settings well formed? | json-lint chklint <dir> |
| Python under the wiki? | python-ruff chklint <dir> |
| New files or new headings? | librarian toc and librarian toc file |
| What links to what? | wiki graph |
| New source, a URL or a file? | wiki ingest <source> --json, then section 18 |
| Ingested pages not refined yet? | wiki ingest --pending --json |
| Empty directory, start a wiki? | wiki init <dir> |
| Template behind the installed package? | wiki check-update, then wiki update --dry-run |
A *-update file appeared? |
Merge it, section 19.8 |
| Ingest or housekeeping done? | git save --description TEXT |
6. wiki
6.1 fiona-assistant wiki with no subcommand prints help and
exits 1.
6.2. init
fiona-assistant wiki init [directory]
6.2.1 Copies the template, substitutes 2026-11-18 with
today's UTC date, creates a git repo, and commits
Initial llm-wiki commit.
6.2.2 .gitignore starts from the packaged default ignore
patterns and includes personal/. An existing .gitignore keeps
its lines; missing patterns are appended.
6.2.3 Paths matched by those default patterns are not copied.
personal/ is gitignored.
6.2.4 Success stdout:
Successfully initialized llm-wiki directory at: <resolved path>
6.2.5 Refuses, and writes nothing, when any of these already
exist: AGENTS.md, fiona-settings.json, wiki/, ingest/,
README.md.
6.3. check-update
fiona-assistant wiki check-update [directory] [--json]
6.3.1 The directory must contain fiona-settings.json. Exit 0
whether or not updates exist.
6.3.2 Human stdout when current: Wiki is up to date.
6.3.3 When something differs, the lines that apply:
Files to update: <N>
Conflicts (owner copy kept): <N>
- <path> (<current> -> <template>) -> <stem>-update<suffix>
Directories to add: <N>
Files to add: <N>
Total: <N> file(s) need attention
Files skipped (locally modified): <N>
6.3.4 A file that lacks a version on either side is compared by
SHA-256. Text hashes fold \r\n and lone \r to \n first, so a
file that differs from the template only in line endings is up to
date.
6.3.5 Equal hashes mean up to date. Different hashes print the first 8 hex digits of each side instead of versions:
- utils/scripts/example.py (sha256 1a2b3c4d -> 9f8e7d6c)
6.3.6 --json prints one object with files_to_update,
conflicts, files_to_add, directories_to_add, files_skipped,
total, and has_updates.
6.3.7 Each conflict has path, update_path,
current_version, and template_version. Entries in
files_to_update and conflicts also carry current_sha256 and
template_sha256: the full hash, or null when versions were
compared.
6.4. update
fiona-assistant wiki update [directory] [--dry-run] [-y|--yes] [-f|--force] [--json]
6.4.1 Updates drifted non-markdown core files in place and adds missing core files.
6.4.2 A differing fiona-settings.json is a conflict: the
owner's file stays byte-for-byte, and the template is written beside
it as fiona-settings-update.json. You merge it during housekeeping
(section 19.8).
6.4.3 Never deletes user files. Never writes inside personal/
or raw/. Never adds or overwrites anything under wiki/ (seeded
at init, then filled by the LLM). Never writes a path matched by
.gitignore.
6.4.4 A confirmed update that had something to report writes
corefiles.json at the wiki root. It lists each compared core
file's version, template version, owner hash, template hash, and the
UTC date.
6.4.5 A later check does not list a file while those four values still match, so a second update the same day stays quiet about a file you already updated.
6.4.6 check-update and --dry-run do not write that file.
Only wiki update writes corefiles.json. Do not edit it by hand,
and do not treat it as a file to merge.
6.4.7 A path in fiona.wiki.update.ignore_files is not an
update, a conflict, an addition, or a merge candidate. The shipped
list is corefiles.json.
6.4.8 Never overwrites an existing markdown file. When the
template has a newer version of one, such as AGENTS.md,
wiki/index.md, wiki/log.md, or wiki/schema.md, the owner's
file stays as it is and the template is written beside it as
<stem>-update.md (AGENTS-update.md, wiki/schema-update.md).
You merge it during housekeeping (section 19.8).
6.4.9 Run --dry-run first. It prints the plan, writes nothing,
and exits 0.
6.4.10 Without --yes or --force the command prompts. On a
pipe that prompt cannot be answered and the command exits 1. Pass
--yes only after the user agrees to the dry run.
6.4.11 Success stdout:
Update complete: <U> file(s) updated, <A> added, <C> conflict(s), <S> skipped.
6.4.12 When <C> is not zero, the next line is:
Merge each <stem>-update<suffix> into its file: run fiona-assistant housekeeping.
6.4.13 MEMORY.md belongs to the wiki. Update adds it only when
it is missing; it never compares or replaces it, and never writes a
MEMORY-update.md.
6.5. sanity
fiona-assistant wiki sanity [directory] [--json] [--non-interactive]
6.5.1 This is the gate for a wiki. Exit 0 only when every check
is clean. Exit 1 otherwise. Requires fiona-settings.json.
6.5.2 Checks, in order: markdownlint, frontmatter_lint,
python-ruff, mdlinter, jsonlint.
6.5.3 Use --json when you will parse the result. The object
has target, checks, total_violations, and passed. Each check
has result (0 pass, 1 fail), violation_count, and violations.
6.5.4 --non-interactive prints progress dots instead of live
bars. It is also automatic when stdout is not a terminal.
6.5.5 A passing human report ends with SANITY PASSED. A
failing report ends with Sanity Failed - <N> checks need attention:.
6.6. graph
fiona-assistant wiki graph [directory] [-o FILE] [--format html|json] [--json]
6.6.1 Defaults: wiki_graph.html in the current directory,
include **/*.md, wikilinks on, external-link nodes off.
6.6.2 A path in fiona.wiki.graph.ignore_files is left out of
the graph. The shipped pattern is */table_of_contents.md, which
also matches table_of_contents.md at the wiki root. A table of
contents links to every page and would hide the real links.
6.6.3 Also: --include-pattern, --exclude-pattern,
--wikilinks / --no-wikilinks,
--external-links / --no-external-links.
--json is an alias for --format json.
6.7. ingest
fiona-assistant wiki ingest <source> [--wiki DIR] [-r|--raw PATH] [-t|--target PATH] [--origin URL] [--raw-only] [-f|--force] [--dry-run] [--json]
fiona-assistant wiki ingest --pending [--wiki DIR] [--json]
6.7.1 <source> is an http:// or https:// URL, or a file
path. The tool is the first phase of an ingest:
- 6.7.1.1 A URL is downloaded into
ingest/as whatever it is: HTML, PDF, text. No credentials are sent. A URL that needs a login stops with exit 4 and writes nothing (section 18.3.4). - 6.7.1.2 The file is archived under
raw/. A file iningest/is moved. Any other file is copied. Nothing already inraw/is changed. - 6.7.1.3 Before archiving, its SHA-256 is compared with every
file in
raw/. Identical bytes are never archived twice: the existing copy is reused (raw_reused: true). When a page already cites that copy, nothing is written andduplicate_pagenames it. - 6.7.1.4 The archive is converted to markdown and written as
one page with
status: raw,confidence: zero, andllm.model: none. - 6.7.1.5 One line is appended to
wiki/log.md.
6.7.2 It does not refine the page, edit wiki/index.md, or
touch any other page. That is your phase, section 18.
6.7.3 Flags:
| Flag | Use |
|---|---|
-r, --raw PATH |
Place the raw copy, relative to raw/. A directory (-r jenkins/tl153) or a file name with an extension. |
-t, --target PATH |
Place the page, relative to wiki/. A directory (-t concepts) or a .md file name. |
--origin URL |
The http(s) URL a local file was saved from. Sets ingest.origin and origin_kind: url, and resolves relative links against it. Local files only. |
--raw-only |
Archive only. Use it when you will convert by hand. |
-f, --force |
Replace an existing page. Ask the user first when that page is refined. |
--dry-run |
Print the plan. Writes nothing in the wiki. A URL is still downloaded, to a temporary directory. |
--pending |
List pages still at status: raw. |
6.7.4 Defaults: raw copies go to raw/articles/ (HTML, text,
markdown), raw/papers/ (PDF), or raw/other/ (no converter).
Pages go to wiki/sources/<slug>.md.
6.7.5 Use -r to group related sources, and -t when the user
names a place or the source belongs beside existing pages.
6.7.6 Converters:
| Converter | Handles | Loses |
|---|---|---|
markdown |
.md |
Nothing. Source frontmatter moves to source_meta. |
text |
.txt, .log |
Structure. The body is one fenced text block. |
html |
web pages | Navigation, buttons, hidden text, scripts, and anything drawn by JavaScript. Doubtful blocks stay, marked for review (section 18.5.2.1). |
pdf |
PDFs with a text layer | Tables, images, columns, and scanned pages. |
6.7.7 Pass --json and read the object: raw_path,
page_path, sha256, raw_reused, duplicate_page, converter,
conversion (complete, partial, none), and warnings. The
page frontmatter carries the same facts in its ingest map.
6.7.8 Exit codes:
| Exit | Meaning | Next |
|---|---|---|
| 0 | Page written, --raw-only, or a duplicate |
Read duplicate_page, conversion, and warnings, then section 18.2. |
| 1 | Error on stderr, nothing written | Fix the argument, or fetch the source another way (section 18.3). |
| 3 | Raw copy archived, no page | Convert by hand (section 18.3). |
| 4 | The URL needs a login. Nothing written, stdout empty even with --json |
Get the source another way (section 18.3.4). |
6.7.9 Exit 4 prints two lines on stderr. The reason is
401 Unauthorized, 403 Forbidden, redirected to <url>, or
login page at <url>:
Error: Authentication required: <url>: <reason>
Next: save it into ingest/, then run: wiki ingest <file> --origin <url>
6.7.10 A redirect counts as a login only when the final host and
path match fiona.wiki.ingest.login_url_patterns. A page whose own
URL holds login, with no redirect, still ingests.
7. librarian
7.1 fiona-assistant librarian with no subcommand lists ..
7.2. list
fiona-assistant librarian list [directory]
7.2.1 Stdout:
Found <N> files in '<directory>':
- <path>
7.3. toc
fiona-assistant librarian toc [directory] [--recursive-toc] [--non-recursive] [--exclude REGEX]
7.3.1 Writes table_of_contents.md in the target folder. Depth
comes from fiona-settings.json.
7.3.2 --exclude is repeatable and takes a regex.
7.3.3 A folder with no markdown prints no markdown files found
and writes nothing.
7.3.4 In-file TOCs:
fiona-assistant librarian toc file <path>
fiona-assistant librarian toc file *
7.3.5 toc file <path> writes an in-file TOC under the H1.
7.3.6 toc file * does that for every markdown file under the
wiki root. It skips personal/, raw/, and table_of_contents.md.
7.3.7 An explicit path inside personal/ or raw/ exits 1 and
writes nothing.
7.3.8 Status lines:
wrote toc in <path>
toc already up to date in <path>
skipped <path> (<reason>)
generated toc for <N> file(s), skipped <M>
7.3.9 The summary line is bulk mode only. A file with no H1 is
skipped <path> (no H1 heading) and is not rewritten.
7.3.10 --sectionized forces heading numbers for that run.
8. mdoctor
8.1 Markdown style (PyMarkdown). No subcommand means
chklint ..
fiona-assistant mdoctor chklint [directory]
fiona-assistant mdoctor list [directory]
fiona-assistant mdoctor fix [directory]
8.2 chklint prints the shared report with header
PyMarkdownlint Violations and exits 0 even when violations exist.
Read SUMMARY and each FILE block. A clean report says
- No violations found.
8.3 fix rewrites files in place. It does not skip personal/
or raw/. Pass a writable directory, never the wiki root, when
those trees are present.
PyMarkdownFix: <N> file(s) fixed
- <path>
8.4 list uses the librarian listing with the prefix
MDoctor: Found <N> files in '<directory>':.
9. fmlint
9.1 Frontmatter. No subcommand means chklint ..
fiona-assistant fmlint chklint [directory]
9.2 Header: Frontmatter Lint Violations. Exits 0 even when
violations exist. Skips personal/ and raw/. A missing directory
exits 1.
9.3 Act on these codes:
| Code | Fix |
|---|---|
| FML001 | Repair the YAML between the --- markers. |
| FML002 | Add a frontmatter block. |
| FML003 | Add name. |
| FML004 | On SKILL.md only, add description. |
| FML005 | On SKILL.md, name must match ^[a-z0-9-]+$. |
| FML006 | On SKILL.md, name must equal the parent folder. |
| FML007 | Add version. |
10. python-ruff
10.1 Python style. No subcommand means chklint ..
fiona-assistant python-ruff chklint [directory]
10.2 Header: Ruff Violations. Exit 0 when the ruff process
itself succeeds, including when violations are listed. There is no
fix subcommand.
11. json-lint
11.1 JSON syntax and style, including fiona-settings.json.
No subcommand means chklint ..
fiona-assistant json-lint chklint [directory]
fiona-assistant json-lint chklint --fix
fiona-assistant json-lint fix [directory]
11.2 Header: JSONLint Violations. Unlike mdoctor, fmlint, and
python-ruff, chklint exits 1 when the report contains violations
and exits 0 when it does not.
11.3 fix and chklint --fix rewrite indentation and trailing
commas. They skip personal/ and raw/.
JSONLintFix: <N> file(s) fixed
- <path>
11.4 Codes: JSN001 syntax, JSN002 indent, JSN003 trailing comma, JSN004 duplicate keys, JSN005 key order, JSN006 line length.
12. git
fiona-assistant git status
fiona-assistant git save --description TEXT
fiona-assistant git snapshot <tag_name> --description TEXT
fiona-assistant git restore <tag_name>
fiona-assistant git clean
fiona-assistant git undo
12.1 These commands act on the git repository that contains the current directory. Run them from the wiki root.
12.2 save runs after each ingest cycle and housekeeping pass,
without asking
(section 2.3).
12.3 snapshot, restore, clean, and undo run only on the
user's request.
12.4 fiona-assistant git with no subcommand prints help and
exits 1.
12.5 --description / -d is required for save and
snapshot. The tool writes the commit message as
<YYYY-MM-DD HH:MM:SS> <description>. Timestamps are UTC.
12.6 Results:
| Command | Success stdout | Refuses when |
|---|---|---|
save -d TEXT |
Committed: <sha> |
Tree is already clean |
snapshot TAG -d TEXT |
Snapshot created: commit=<sha>, tag=<tag> |
Save would refuse |
restore TAG |
Restored to: <sha> |
Tree is dirty |
clean |
Working tree cleaned. All changes discarded. |
Tree is already clean |
undo |
Undo to: <sha> |
Tree is dirty, or only one commit exists |
status |
Status: clean or Status: dirty, then git status |
— |
12.7 On failure the tool prints Error: <message> and exits 1.
12.8 snapshot commits, then creates an annotated tag
<YYYY-MM-DD_HH-MM-SS>_<tag_name>.
12.9 restore accepts the full tag or the suffix and adds a new
commit. History before that commit stays.
12.10 clean is git reset --hard HEAD and git clean -fd.
undo is git reset --hard HEAD~1.
12.11 Do not use clean, undo, or restore to discard work
the user has not agreed to drop.
13. How to read a run
13.1 Shared report shape for mdoctor, fmlint, python-ruff, and json-lint:
<Linter Name> Violations
TARGET: <path>
- DEFINITIONS:
- FILE: <path>
- SUMMARY:
- Total files with violations: <N>
- Total violations: <N>
13.2 Trust the report, not the exit code, for mdoctor, fmlint,
and python-ruff. Trust the exit code for json-lint and for
wiki sanity.
13.3 An invalid directory prints
Error: '<path>' is not a valid directory. on stderr and exits 1,
unless a command above states a different message.
14. Work loop
14.1 After you edit a page:
- 14.1.1 Bump frontmatter
versionand setupdatedto the edit date. On a page underwiki/, set the quality signals in section 15. Patch for a clarification, minor for a new section, major for a breaking change. - 14.1.2 A new page is listed in
wiki/index.md. - 14.1.3 Append one dated line to
wiki/log.md, and bump that file too. - 14.1.4
fiona-assistant fmlint chklint <dir> - 14.1.5
fiona-assistant mdoctor chklint <dir> - 14.1.6 If headings changed,
fiona-assistant librarian toc file <path>. If files were added or removed,fiona-assistant librarian toc <folder>. - 14.1.7 If you touched JSON,
fiona-assistant json-lint chklint <dir>. - 14.1.8 If you touched Python,
fiona-assistant python-ruff chklint <dir>. - 14.1.9 Before you call the wiki healthy,
fiona-assistant wiki sanity . --json --non-interactive. - 14.1.10 When sanity passes, save (section 2.3).
14.2 Relative markdown links must point at a real file.
Wikilinks [[page]] must match a markdown file stem. Both are
checked by mdlinter inside wiki sanity. Follow
schema for page names, tags, and link
style.
14.3 Ingest drops files in ingest/. Archive sources under
raw/ and do not edit them after that. Synthesized pages go under
wiki/ (concepts/, entities/, comparisons/, queries/). The
full ingest is section 18.
15. Frontmatter
15.1 Required on every markdown file: name, version. Bump
version when the page is edited. Set updated when you edit.
15.2 Required on every page under wiki/: the quality signals
confidence, llm, contested, and contradictions. Set them in
the same edit. fmlint enforces name and version only.
15.3 Fields:
| Field | Required | Rule |
|---|---|---|
name |
yes | Wiki pages use lowercase and hyphens. |
version |
yes | Semver. |
title |
no | Human title. |
created |
no | YYYY-MM-DD |
updated |
no | YYYY-MM-DD. Set it when you edit. |
type |
no | entity, concept, comparison, query, summary, toc |
tags |
no | From the taxonomy in schema.md. |
sources |
no | Paths such as raw/articles/source-name.md. |
confidence |
wiki pages | trusted, high, medium, low, or zero. See section 15.4.2. |
llm |
wiki pages | model is required. Add reasoning when the model reports a level. |
contested |
wiki pages | true when a claim is disputed, otherwise false. |
contradictions |
wiki pages | Other page slugs that disagree. [] when none. |
description |
SKILL.md only | Required when the file name is SKILL.md. |
status |
ingested pages | raw from wiki ingest. You set refined (section 18.5). |
ingest, source_meta |
ingested pages | Written by wiki ingest. Check them (section 18.4). Keep them when you refine. |
15.4. Quality signals
15.4.1 On every page under wiki/, fill these before you finish
the edit. Refresh them when you change the page. llm.model is the
model that made this edit.
15.4.2 confidence is how sure the page is:
- 15.4.2.1
trusted: the user stated it, or it is copied from a cited source, with no inference. - 15.4.2.2
high: more than one source agrees, or one source and no known contradiction. - 15.4.2.3
medium: one source, or a synthesis you are reasonably sure of. - 15.4.2.4
low: inference, thin evidence, or an open gap. - 15.4.2.5
zero: unknown, or not checked.
15.4.3 llm records who wrote the page:
llm:
- model: <model name>
- reasoning: high
- 15.4.3.1
modelis required. Usenonewhen no model wrote the page. - 15.4.3.2 Use
Autowhen the harness routes to a model automatically and the model cannot be determined. - 15.4.3.3 Add
reasoningwhen the model reports a level.
15.4.4 contested is true when any claim on the page is
disputed by a source or by another page. Otherwise false.
15.4.5 contradictions lists the name of each page that
disagrees. Use [] when none do.
15.4.6 SKILL.md name must match ^[a-z0-9-]+$ and the
parent folder.
16. Checks with no own command
16.1 wiki sanity also runs mdlinter and the same
frontmatter, ruff, and JSON checks. There is no
fiona-assistant mdlinter command.
| Code | Meaning |
|---|---|
| MDL001 | A relative markdown link does not resolve to a file. |
| MDL002 | A [[wikilink]] matches no page stem. |
| MDL003 | A table row continues onto the next line. |
16.2 pycustomlint (PYC001 inline import, PYC002 import after
code, PYC003 late declaration) runs in the product sanity gate, not
as a fiona-assistant subcommand.
17. Do not call
17.1 These are not implemented. Do not invent flags for them.
- 17.1.1
fiona-assistant html-js-lint - 17.1.2
fiona-assistant setup - 17.1.3
fiona-assistant pycustomlint - 17.1.4
fiona-assistant python-ruff fix
18. Ingest cycle
18.1 An ingest has two phases. wiki ingest (section 6.7)
converts the source into a page at status: raw. You refine that
page to status: refined. The ingest is done only when both phases
are done. The pattern is section 3.1 of
llm-wiki-mod.
18.2. Convert
- 18.2.1 When the raw or page location is not obvious, run
fiona-assistant wiki ingest <source> --dry-run --jsonand checkraw_pathandpage_path. - 18.2.2 Run
fiona-assistant wiki ingest <source> --json, with-rand-twhen needed. - 18.2.3 Read the result. When
duplicate_pageis set, the same bytes are already archived and ingested. Nothing was written.- 18.2.3.1 Refine that page if it is still
status: raw, else stop and tell the user which page holds the source. - 18.2.3.2 Use
--forceonly when the user wants it converted again.
- 18.2.3.1 Refine that page if it is still
- 18.2.4 On exit 0 with
conversion: completeand no warning that lost content, check the metadata (section 18.4), then refine (section 18.5). Otherwise decide with section 18.3.- 18.2.4.1
html sweep: <k> keep, <r> review, <d> droponly counts the blocks of an HTML page. It is not lost content.
- 18.2.4.1
- 18.2.5 On exit 4, follow section 18.3.4. Do not retry the URL.
18.3. Convert by hand
18.3.1 The tool is the default, not a rule. You decide when the source is too complex for it and read the source yourself. Convert by hand when:
- 18.3.1.1 The command exited 3: no converter, or conversion failed.
- 18.3.1.2
conversionispartialand the warnings show lost text: no text layer (a scanned PDF), no text content (a page drawn by JavaScript or a login page), or pages with no text. - 18.3.1.3 Layout carries the meaning: tables, multi-column papers, forms, slides, spreadsheets, diagrams, or a bundle of logs.
- 18.3.1.4 The command exited 4: the URL needs a login. Section 18.3.4 gets the file. The tool still converts it.
18.3.2 How:
- 18.3.2.1 Make sure the raw copy exists. When it does not, run
fiona-assistant wiki ingest <file> --raw-only --json.- 18.3.2.1.1 Without the tool, first compute the file's
SHA-256 (
sha256sum <file>, orGet-FileHash -Algorithm SHA256 <file>in PowerShell). - 18.3.2.1.2 Compare it with the files under
raw/of the same size and withingest.sha256inwiki/pages. Reuse a match. Do not archive the same bytes twice. - 18.3.2.1.3 With no match, copy the file (move it when it is
in
ingest/) to the default folder in section 6.7.4, under a lowercase hyphenated name that is not taken.
- 18.3.2.1.1 Without the tool, first compute the file's
SHA-256 (
- 18.3.2.2 Read the raw file with your own tools. Never edit it.
- 18.3.2.3 Write the page where the tool would have put it, with
the complete frontmatter in section 18.6. Set
ingest.converter: agent, and fillsha256,size_bytes,media_type, andfetchedfrom the raw file. - 18.3.2.4 You may write the refined page in one pass. Then follow section 18.5.3 onward.
18.3.3 When the tool archived the wrong file or to the wrong
place, tell the user. Do not move or delete anything under raw/.
18.3.4 A URL that needs a login (exit 4). The tool cannot log in. Get the source with these steps, in order:
-
18.3.4.1 Use a tool you already have that reads that host with the user's access: an MCP server for Confluence, SharePoint, Jenkins, or a ticket system, or an authenticated script in
utils/scripts/. Save what it returns intoingest/<slug>.<ext>in its own format: HTML as.html, a PDF as.pdf, plain text as.txtor.md. Then run theNext:command with that file:fiona-assistant wiki ingest ingest/<slug>.<ext> --origin <url> --json -
18.3.4.2 When no tool has access, stop and ask the user to save the page into
ingest/, for example with the browser's Save As or Print to PDF. Name the URL, the folder, and the command you will run once the file is there. Do not retry the URL. -
18.3.4.3 Never ask the user for a password, token, or cookie. Never put credentials in a URL, a command line, a page, or the log.
-
18.3.4.4 A tool that returns a summary instead of the source is not the source. Archive what it returned as it is, and add a line to
ingest.warningsthat names the tool it came through.
18.4. Check the metadata
18.4.1 The tool fills every key in section 18.6, but it reads the source mechanically. Check the frontmatter against the source before you refine, and fix what is wrong.
18.4.2 You may edit title, type, tags, source_meta,
ingest.conversion, and ingest.warnings. You may not hand-edit
ingest.sha256, ingest.size_bytes, ingest.fetched,
ingest.media_type, or ingest.tool.
| Key | Check | May edit |
|---|---|---|
title |
The real title, not a site name, a file name, or Untitled. |
yes |
type |
Usually summary for a source page. |
yes |
tags |
From the schema taxonomy. | yes |
sources |
Points at the raw file, and that file exists. | only when wrong |
source_meta |
Author, dates, and description match the source. Add values the converter missed, such as a date printed in the body. | yes |
ingest.conversion |
partial when you see lost text, tables, or pages. |
yes |
ingest.warnings |
Add what you found lost. Leave the tool's lines. | yes |
ingest.origin, origin_kind, final_url |
Match the URL or path the user gave. | only when wrong |
ingest.sha256, size_bytes, media_type, fetched, tool |
Facts computed by the tool. | no |
18.4.3 Verify ingest.sha256 against the raw file with
sha256sum or Get-FileHash.
18.4.4 When a computed fact is wrong, re-run the ingest with
--force or tell the user. Do not hand-edit it.
18.4.5 Bump the page version patch and updated when you edit
the metadata.
18.5. Refine
- 18.5.1
fiona-assistant wiki ingest --pending --jsonlists the pages still atstatus: raw.- 18.5.1.1 Without the tool, search
wiki/forstatus: raw. - 18.5.1.2 Check each page's metadata first (section 18.4).
- 18.5.1.3 A markdown source keeps its body. The tool writes
the page frontmatter when the source did not already have it.
Source frontmatter is in
source_meta. - 18.5.1.4 A text source (
.txt,.text,.log) is one fencedtextblock plus that frontmatter, still atstatus: raw. Rewrite that fence. The tool does not refine it.
- 18.5.1.1 Without the tool, search
- 18.5.2 Read the page and the source it cites. Open the raw
file when
ingest.conversionispartialor a claim looks garbled.- 18.5.2.1 An HTML page can hold blocks between
<!-- fiona:review <reason> -->and<!-- /fiona:review -->. The tool kept them but doubts them. Decide each one: keep it by deleting its two marker lines, or delete the block with its markers. A refined page holds nofiona:reviewmarker. - 18.5.2.2
chrome: it sits in an aside, form, dialog, landmark role, or a page header or footer. Usually delete. - 18.5.2.3
repeat: the same text appeared earlier. Keep it only when the repeat matters, such as a quote in a reply. - 18.5.2.4
links: mostly link text, such as a reference list or a link menu. Keep references; delete menus. - 18.5.2.5
short: a paragraph of fewer thanhtml.min_wordswords, such as a button label or a counter. Keep a number that a nearby sentence explains.
- 18.5.2.1 An HTML page can hold blocks between
- 18.5.3 Rewrite the page as a source summary:
- 18.5.3.1 The first paragraph says what the source is and why it matters.
- 18.5.3.2 Keep facts, numbers, decisions, dates, and names. Keep a short code or log excerpt when it backs a claim.
- 18.5.3.3 Drop boilerplate: menus, cookie notices, repeated headers and footers, page numbers.
- 18.5.3.4 Stay under the 200-line split rule in the schema.
Detail stays in the raw file, which
sourcescites.
- 18.5.4 Add at least two outbound links, as the schema asks. Link the concept and entity pages the source touches.
- 18.5.5 Update or create those concept and entity pages, using
the page thresholds in the schema. When the source disagrees with
a page, set
contestedandcontradictionson both. - 18.5.6 When the page belongs elsewhere, move it and fix every inbound link.
- 18.5.7 Set the frontmatter:
status: refined,version: 1.0.0,updated,type,tagsfrom the taxonomy, and the quality signals from section 15 with your model inllm. Keepsources,source_meta, and everyingestkey. - 18.5.8 Add the page to
wiki/index.md. Append- YYYY-MM-DD - refined <page path> from <raw path>towiki/log.md. - 18.5.9 Run the work loop in section 14, ending with
wiki sanity.
18.5.10 A page is refined when status is refined, version
is 1.0.0 or later, the quality signals are set and llm.model is
not none, the page is listed in wiki/index.md, and wiki/log.md
has a line for the refinement.
18.5.11 The ingest is done when every page from the run meets
section 18.5.10 and wiki sanity passes. Then save it
(section 2.3).
18.6. Raw page frontmatter
18.6.1 wiki ingest writes every key below, even when a value
is empty ([], {}, or null). Write the same when you convert by
hand.
---
name: <slug>
version: 0.1.0
title: <title>
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: summary
status: raw
sources: [raw/<category>/<slug>.<ext>]
source_meta: {author: <name>}
ingest:
origin: <url or file path>
origin_kind: url
final_url: null
fetched: YYYY-MM-DDTHH:MM:SSZ
media_type: text/html
size_bytes: 0
sha256: <64 lowercase hex>
raw_reused: false
converter: <converter name, or agent>
conversion: complete
warnings: []
tool: fiona-assistant <version>
tags: []
confidence: zero
llm:
- model: none
contested: false
contradictions: []
---
18.6.2 When you write it by hand, set llm.model to your model
and confidence from section 15.4.2.
19. Housekeeping
fiona-assistant housekeeping [directory] [--json]
19.1 One call runs the maintenance routine and tells you what needs work.
19.2 Run it when the user asks for maintenance, after
wiki update, and before you call the wiki healthy.
19.3 It writes only wiki_graph.html. It never runs
wiki update, merges, or fixes anything. That is your part.
19.4 Steps:
| Step | Status when not clean | You do |
|---|---|---|
check-update |
WARN: the template has updates, conflicts, or additions |
Ask the user, then wiki update --dry-run and wiki update --yes. |
merge |
FAIL: a file whose stem ends with -update exists |
Section 19.8. |
ingest |
WARN: a page under wiki/ is at status: raw |
Refine it, section 18.5. |
sanity |
FAIL: a wiki sanity violation |
Fix it, section 14. |
graph |
WARN: a page under wiki/ has no link in or out |
Link it from a related page or from wiki/index.md. |
19.5 Every step runs, even after one fails. Exit 0 when no step
is FAIL; WARN steps do not fail the run.
19.6 Pass --json and read steps[].status, details, and
next: next is the action to take. The human report ends with
HOUSEKEEPING PASSED, or
HOUSEKEEPING FAILED - <N> step(s) need attention: <names>.
19.7 Work through the FAIL steps, then run housekeeping again
until it passes. Fix a WARN when the user's task covers it;
otherwise report it. Then save the pass
(section 2.3).
19.8. Merge an update file
19.8.1 wiki update yields to the owner. When the packaged
template has a newer version of a markdown file the owner may have
edited, such as AGENTS.md, wiki/index.md, wiki/log.md, or
wiki/schema.md, the owner's file stays as it is and the template
is written beside it as <stem>-update.md.
19.8.2 AGENTS-update.md belongs to AGENTS.md;
wiki/schema-update.md belongs to wiki/schema.md.
19.8.3 A differing fiona-settings.json is the same kind of
conflict: the owner's file stays, and the template is
fiona-settings-update.json.
19.8.4 The update file is the new template text, as wiki init
would write it. You decide how the two become one file:
- 19.8.4.1 Read both files. Compare them, for example with
git diff --no-index <file> <stem>-update.md. - 19.8.4.2 Keep every owner edit: their wording, tags, sections, index entries, and log lines. The owner wins where the two disagree on content.
- 19.8.4.3 Take what the template adds or corrects: new sections, new rules, new frontmatter fields, and fixed command names, flags, or paths. A tool contract (a command, a flag, a required field) comes from the template.
- 19.8.4.4 For
wiki/index.mdandwiki/log.md, keep the owner's entries. Take only new structure from the template. Never replace the owner's entries with the template's. - 19.8.4.5 Set
versionto at least the update file'sversion, andupdatedto today. Keep the owner'screated. A lower version brings the conflict back on the nextwiki update. - 19.8.4.6 Delete the update file.
- 19.8.4.7 Append
- YYYY-MM-DD - merged <stem>-update.md into <file>towiki/log.md, and bump that file. - 19.8.4.8 Run
fiona-assistant housekeepingagain.mergepasses when no update file is left.
19.8.5 For fiona-settings-update.json, merge by the settings
rule:
- 19.8.5.1 Start from the template object.
- 19.8.5.2 For each user key, if both sides are objects, merge recursively; otherwise the user value replaces the template value.
- 19.8.5.3 Keep new template keys the user does not set.
- 19.8.5.4 Write the result as JSON with indent 2 and a trailing
newline, then delete
fiona-settings-update.json. - 19.8.5.5 Log the merge the same way as section 19.8.4.7.
19.8.6 Settings have no version field. Line endings alone are
not a difference. A later wiki update lists the file again only
when the text still differs and corefiles.json does not already
record that same version and hash pair.
19.8.7 When you cannot tell whether an owner edit or a template change should win, ask the user.
19.8.8 Do not delete an update file you have not merged unless the user says to drop it.
19.8.9 When the target file is missing, ask the user whether to restore it from the update file.