MEMORY.md and skill memory template, ingest auth and html_sweep, TOC slug fix, run_tests CI output, and matching tests. Excludes GitLab CI and publishing docs.
210 KiB
name, version, title, created, updated, type
| name | version | title | created | updated | type |
|---|---|---|---|---|---|
| Fiona-Assistant Specification | 1.18.0 | Project Spec Sheet | 2026-09-23 | 2026-10-15 | summary |
Fiona-Assistant Specification
- 1. Product Overview
- 2. Package and Runtime
- 3. llm-wiki Template
- 4. Command Catalog
- 5. Settings Schema
- 6. Violation Rule Catalog
- 7. Feature Requirements
- 7.1. wiki
- 7.2. housekeeping
- 7.3. librarian
- 7.4. mdoctor
- 7.5. fmlint
- 7.6. mdlinter
- 7.7. pycustomlint
- 7.8. python-ruff
- 7.9. Shellcheck
- 7.10. Markdown Code Blocks
- 7.11. json-lint
- 7.12. Git Operations
- 7.13. Backup Script
- 7.14. Test and Sanity Runners
- 7.15. html-js-lint
- 7.16. settings setup
- 7.17. Logging
- 7.18. Documentation
- 7.19. Tool Roles
- 7.20. Wiki Root Discovery
- 7.21. Bootstrap install modes
- Appendix A. Non-Goals
- Appendix B. Priority Order
- Appendix C. Open Questions
- Appendix D. Maintainer Notes
This document is the build contract for Fiona-Assistant. A reader with
this file, and no source tree, must be able to produce the same
observable software. Status values are Implemented, Partially Implemented, Planned, and Won't Do.
The revision history of this document is in
CHANGELOG. Add an entry there, newest first, each
time the version above changes.
Each feature section starts with a Status line. Requirements use
- *N.M.K.*. Each *acceptance* sits under the requirement it tests.
NOT_IMPLEMENTED marks work that is specified and not built yet.
Class names, file paths, and history live in Appendix D.
1. Product Overview
Fiona-Assistant is a CLI toolkit that manages, organizes, and checks LLM wiki content with deterministic scripts. Reserve LLM tokens for creative and analytical work.
1.1. Document Conventions
Status: Implemented
- 1.1.1. Main sections use
## N. Title. Subsections use### N.M. Title. Deeper headings use#### N.M.K. Title.- acceptance: Every heading follows that numbering.
- 1.1.2. A requirement is
- *N.M.K.* <text>. A group is numbered the same way, and each item under it adds one segment, for example*7.14.1.*then*7.14.1.1.*. Its acceptance is the next nested- *acceptance*: <text>, and that acceptance describes this requirement only.- acceptance: No acceptance describes a neighboring requirement.
- acceptance: The shared-engine bullets in section 7.14 are
numbered
7.14.1and7.14.1.1, not plain dashes.
- 1.1.3. Unbuilt requirements start with
`NOT_IMPLEMENTED`.- acceptance: Every planned item carries that tag.
- 1.1.4. The block between
<!-- toc-start: headings 2..6 -->and<!-- toc-end -->is generated bylibrarian toc file. Leave that block to the generator.
1.2. Constraints
These apply to every feature.
- 1.2.1. Tool reports are parseable and use the shared shapes in
sections 4, 6, and 7.
- acceptance: Two linters that find violations print the same section order from section 6.1.
- 1.2.2. A command that needs a human decision prompts on a TTY.
The same command accepts an explicit flag (
--force,--yes, or--non-interactive) and then runs without a prompt.- acceptance:
wiki updateon a non-TTY declines unless--forceor--yesis set.
- acceptance:
- 1.2.3.
personal/andraw/are read-only for every automated tool. Tools may resolve links that point into those zones. The one exception iswiki ingest(7.1.5.3.): it may add a new file underraw/. It never modifies, renames, or deletes a file already there.- acceptance:
wiki updateleaves every file underpersonal/andraw/byte-for-byte unchanged. - acceptance: A second
wiki ingestrun leaves every file that was already underraw/byte-for-byte unchanged. - acceptance: Ingesting bytes whose SHA-256 matches any file
already under
raw/, from any path or URL, adds no file underraw/(7.1.5.3.3.).
- acceptance:
- 1.2.4. Code changes follow test-first development.
python scripts/run_tests.pyis green, thenpython scripts/run_sanity.pyis green, before a change is finished.- acceptance: A sanity run below the coverage gate in section 5.2 fails even when every test passes.
- 1.2.5. Python passes Ruff. Markdown passes PyMarkdown with the
rules in section 5.1.
- acceptance: An unused import is reported by
python-ruff chklintwith file, line, column, and rule code.
- acceptance: An unused import is reported by
- 1.2.6. Authored lengths in HTML and CSS use
emor another relative unit (rem,%,vh,vw). They are not written inpx. The wiki graph page in section 7.1.4 is that web surface. A position read from the layout engine is written back inrem. A theme length number uses the same scale: 16 is1em.- acceptance: The graph template contains no
pxlength.
- acceptance: The graph template contains no
- 1.2.7.
NOT_IMPLEMENTEDAn expected failure, such as a missing path, a refusal, or bad input, prints oneError: <message>line on stderr and exits 1. It prints no Python traceback. A traceback is logged only atDEBUG.- acceptance: A second
wiki initon the same directory writes no line containingTracebackon stderr (7.1.1.4.).
- acceptance: A second
2. Package and Runtime
Status: Partially Implemented
Python >= 3.11 (also 3.12 and 3.13). The default development
install from the repository root is pip install -e ".[dev]".
bootstrap --local installs the same tree as a normal package
(pip install .). Section 7.21 defines those modes. The build
requires setuptools 61 or newer.
Runtime dependencies:
| Package | Minimum |
|---|---|
| pymarkdownlnt | 0.9.0 |
| ruff | 0.16.8 |
| pyyaml | 6.0.3 |
| GitPython | 3.1.0 |
Development extras: pytest>=7.0, pytest-cov>=4.0, pytest-mock,
pylint. html5validator is not a dependency until section 7.15
is implemented. beautifulsoup4, markdownify, and pypdf become
runtime dependencies when section 7.1.5 is implemented.
One importable package, fiona, lives under src/fiona/. Its
subpackages are librarian, mdoctor, customlinter,
python_ruff, gittool, sanity_runner, and wiki. The wiki
template is package data at src/fiona/data/llm_wiki/ and is loaded
with importlib.resources. It is not an importable module. Tests
live in repo-root tests/ and are not installed. scripts/ holds
settings_dev.json, shell helpers, and the launchers
scripts/run_tests.py and scripts/run_sanity.py.
Console scripts:
| Script | Entry |
|---|---|
fiona-assistant |
fiona.__main__:main |
librarian |
fiona.librarian.librarian:main |
mdoctor |
fiona.mdoctor.mdoctor:main |
python-ruff, fmlint, json-lint, and git are reached only
through fiona-assistant. html-js-lint is not installed until
section 7.15 is implemented.
Coverage measures src/fiona, omitting tests. The config lives in
pyproject.toml. The gate percentage is section 5.2.
Logging: every CLI entry calls setup_logging() before work. Level
order is LOG_LEVEL environment variable, then fiona.log_level in
fiona-settings.json, then WARNING. Records go to stderr. When
fiona.file_log_location is set, a file handler writes lines
%(asctime)s %(levelname)s %(name)s: %(message)s at or above
fiona.file_log_level (fallback: fiona.log_level). A relative path
is resolved from the current working directory. An unopenable path
logs a warning and keeps stderr logging. Human reports stay on
stdout. Package loggers set their level explicitly because
pymarkdown resets the root logger mid-run.
- 2.1. The three console scripts above are installed by
pip install -e ..- acceptance:
fiona-assistantwith no arguments prints help and exits 0.
- acceptance:
- 2.2.
html-js-lintis not an installed script until section 7.15 exists.- acceptance: A fresh install does not fail at import because of
a missing
html_js_lintpackage.
- acceptance: A fresh install does not fail at import because of
a missing
- 2.3.
NOT_IMPLEMENTEDfiona-assistant --versionprintsfiona-assistant <package version>on stdout and exits 0. The text is the same stringwiki ingestwrites toingest.tool(7.1.5.5.3.).- acceptance: The stdout of
--versionequals theingest.toolvalue of a page ingested by the same install.
- acceptance: The stdout of
3. llm-wiki Template
Status: Implemented
wiki init copies this tree from the packaged template. Text files
replace every DATE_PLACEHOLDER with the current UTC date
YYYY-MM-DD. Binary files are copied unchanged. A glob in
fiona.llm-wiki.ignore_files skips that file, or that directory and
its subtree. A missing settings file or a missing key copies
everything. A non-list ignore_files value raises ValueError with
the text fiona.llm-wiki.ignore_files must be a list of strings.
AGENTS.md
MEMORY.md
README.md
fiona-settings.json
constellation/colorful.json
constellation/dark.json
constellation/grayscale.json
constellation/night-sky.json
constellation/professional.json
table_of_contents.md
ingest/README.md
personal/README.md
raw/README.md
wiki/schema.md
wiki/index.md
wiki/log.md
utils/README.md
utils/scripts/example.py
utils/scripts/map.md
utils/skills/README.md
utils/skills/fiona/SKILL.md
utils/skills/fiona/markdown_rules.md
utils/skills/fiona/llm-wiki-mod.md
utils/skills/python-tdd/SKILL.md
utils/skills/memory/SKILL.md
utils/skills/memory/MEMORIES.md
utils/personas/default/SOUL.md
utils/personas/template/SOUL.md
utils/skills_local/README.md
NOT_IMPLEMENTED refine/README.md joins this tree (7.1.5.15.10.).
The shipped fiona-settings.json is the default document in
section 5.1. wiki/schema.md is the page-type and tag taxonomy.
This spec's frontmatter table in section 6.2 is the field contract;
where the two disagree, this spec wins.
3.1. What Counts as a Wiki
A directory is an llm-wiki when it contains fiona-settings.json.
wiki init refuses when any of these already exist:
AGENTS.md, fiona-settings.json, wiki/, ingest/, README.md.
3.2. Core Files and Read-only Zones
Core files, matched by name at the wiki root:
AGENTS.mdfiona-settings.jsonREADME.mdtable_of_contents.md
Core directories (every file under them is core):
wiki/ingest/personal/raw/utils/constellation/NOT_IMPLEMENTEDrefine/(7.1.5.15.10.)
Read-only zones, including the zone directory itself:
personal/raw/
wiki/ is copied by wiki init and then left to the LLM.
wiki update does not add, replace, or delete any path under
wiki/. The only file it writes there is an update file for a
template page that is newer than the wiki's copy (7.1.2.11.).
MEMORY.md belongs to the wiki once it is there. wiki update adds
it when it is missing and never compares or replaces it after that
(3.4.4.).
wiki update adds missing core files and directories. It never
overwrites an existing markdown file: when the template carries a
newer version, it writes <stem>-update.md beside the file and
leaves the owner's file as it is. A differing
fiona-settings.json is the same kind of conflict: the owner's
file stays, and the template is written as
fiona-settings-update.json (7.1.2.3.). A confirmed update
that changes or reports anything also writes corefiles.json
at the wiki root (7.1.2.14.). That file is not part of the
template. Only wiki update writes it. A glob in
fiona.wiki.update.ignore_files is not updated (7.1.2.15.).
The shipped list is corefiles.json. It never deletes user files. It
never writes inside a read-only zone, so a missing file under
personal/ or raw/ is not added back. It
never writes a path matched by the repository .gitignore or by
the wiki's own .gitignore.
After the copy, wiki init creates a git repository and writes
.gitignore. A new file starts with the fiona-assistant repository
.gitignore (the same patterns, including __pycache__/, *.pyc,
and *fiona.log). When this package is not the source checkout,
that text is the packaged default.gitignore. The file adds
personal/ when that pattern is missing. The set also ignores
Obsidian's per-user vault state, .obsidian/workspace*.json and
.obsidian/cache, so a wiki opened as an Obsidian vault stays
clean between saves (3.2.3.).
An existing .gitignore keeps every line it already has; missing
patterns from that set are appended. Init then stages everything
and commits Initial llm-wiki commit. Template paths that match
the repository .gitignore are not copied. personal/ and raw/
are still copied. personal/ stays untracked. If git init fails,
the copy still counts as success and stdout adds
Note: Git repository initialization failed: <error>.
- 3.2.1. An empty directory becomes the tree above, with dates
substituted, and a git commit that does not track
personal/.- acceptance:
personal/is absent fromgit ls-filesafterwiki init.
- acceptance:
- 3.2.2. A second
wiki initraisesFileExistsErrorwhose message names each conflicting indicator, and writes nothing.- acceptance: An existing
README.mdalone is enough to refuse, and that file's bytes are unchanged.
- acceptance: An existing
- 3.2.3. The
.gitignorewritten bywiki initignores Obsidian's per-user state and keeps the shared vault settings tracked.- acceptance: After
wiki init,git check-ignorematches.obsidian/workspace.json,.obsidian/workspace-mobile.json, and.obsidian/cache, and does not match.obsidian/app.json.
- acceptance: After
3.3. Deployed Wiki Rules
Status: Implemented
Only the template tree is deployed. A wiki does not know this spec,
the root AGENTS.md, scripts/, or tests/. The template
AGENTS.md is the entry point: it says what the wiki is and loads
the Fiona skill, which loads llm-wiki-mod.md. The product rule
"never commit without permission" (project agent rule 2.4) covers
this repository only.
- 3.3.1. No markdown file in the template references a file or
rule outside the template:
SPEC,project agent rule, orscripts/run_.- acceptance: A scan of every template
*.mdfinds none of those strings.
- acceptance: A scan of every template
- 3.3.2. The template
AGENTS.mdlinks the Fiona skill andllm-wiki-mod.md.- acceptance: Both relative links appear in that file.
- 3.3.3. A deployed wiki commits with
fiona-assistant git save --description TEXTafter each ingest cycle and each housekeeping pass.clean,undo, andrestorerun only when the user asks.- acceptance: The template
AGENTS.mdand the Fiona skill both containgit save, and neither says to commit only when asked.
- acceptance: The template
- 3.3.4. The template
wiki/log.mdholds one seed entry datedDATE_PLACEHOLDER.- acceptance: The log body has exactly one bullet.
3.4. Agent Memory
Status: Implemented
MEMORY.md at the wiki root is the agent's memory of how the owner
wants this wiki run: standing preferences, corrections, repeated
request patterns, and facts a run verified about the wiki's tools
and setup. Domain knowledge goes to pages under wiki/, not here.
The template ships the rules for the file and empty categories.
From then on the file grows with the wiki it belongs to.
- 3.4.1. The template ships
MEMORY.mdat its root with frontmattername: memoryand aversion.wiki initcopies it with the rest of the tree.- acceptance: The template
MEMORY.mdexists and its frontmatter hasname: memoryandversion.
- acceptance: The template
- 3.4.2.
MEMORY.mdis sectionized as the template'sutils/skills/sectionize-markdown/sectionize-markdown.mddescribes. Every heading below the title is numbered. Every list item outside the TOC and code blocks starts with a bold id that extends the number of its section. No id repeats.- acceptance: A scan of the template
MEMORY.mdfinds no unnumbered heading, no list item without an id, no id outside its section, and no duplicate id.
- acceptance: A scan of the template
- 3.4.3. Section 1 of
MEMORY.mdsays when to read it, when to write an entry, how to write one, and how entries evolve. An entry uses the knowledge-entry shape of sectionize-markdown section 4. An entry never overrides the boundaries of the templateAGENTS.md.- acceptance:
MEMORY.mdhas the subsections1.1 When to read,1.2 When to write,1.3 How to write, and1.4 How the memory evolves.
- acceptance:
- 3.4.4.
MEMORY.mdevolves with the wiki, not with the template.wiki updateadds it when the wiki has none. Once the wiki has the file, check-update,wiki update, and thecorefiles.jsonrecord leave it out, whatever the template version: it is never compared, replaced, or written asMEMORY-update.md. A match infiona.wiki.update.ignore_files(7.1.2.15.) also stops the add.- acceptance: A template
MEMORY.mdwith a higher version than the wiki copy is absent from check-update.wiki update --yesleaves the wiki copy byte-for-byte unchanged, writes noMEMORY-update.md, andcorefiles.jsonhas noMEMORY.mdentry. - acceptance: A wiki without
MEMORY.mdlists it under files to add.
- acceptance: A template
- 3.4.5. The template
AGENTS.mdlinks./MEMORY.mdand tells the agent to read it once the Fiona skill is loaded.- acceptance: The relative link appears in that file.
- 3.4.6. The template
AGENTS.mdtells the agent to updateMEMORY.mdwhenever an important memory comes up, and whenever the user explicitly asks it to remember something.- acceptance: That file says to update
MEMORY.mdon an important memory and when the user explicitly asks.
- acceptance: That file says to update
3.5. Skill Memory
Status: Implemented
A skill can keep a memory of its own: what its users want from that
skill, kept across sessions. The file is MEMORIES.md beside the
skill's SKILL.md. The template ships the instructions and a blank
file under utils/skills/memory/, so an agent asked to create a skill
with memory has both. Wiki-wide preferences stay in MEMORY.md
(3.4.).
- 3.5.1. The template ships
utils/skills/memory/SKILL.mdwith frontmattername: memoryand aversion. It says what a skill memory holds, how to give a skill one, and how the skill'sSKILL.mdloads it.- acceptance: The file exists, its frontmatter has
name: memoryandversion, and it links./MEMORIES.mdand the wiki rootMEMORY.md.
- acceptance: The file exists, its frontmatter has
- 3.5.2. The template ships
utils/skills/memory/MEMORIES.md, a blank memory for one skill, with frontmatternameandversion. It is sectionized as 3.4.2. describes, and its section 1 has the subsections of 3.4.3..- acceptance: The same scans as 3.4.2. and 3.4.3. pass on that file.
4. Command Catalog
Status: Implemented
One command tree. Optional [directory] defaults to . today.
Wiki-root discovery (section 7.20) is not built. An invalid
directory prints Error: '<path>' is not a valid directory. on
stderr and exits 1, unless a command below states a different
message.
fiona-assistant with no command prints help and exits 0.
fiona-assistant git with no subcommand prints git help and exits 1.
fiona-assistant wiki with no subcommand prints wiki help and
exits 1.
4.1. librarian
fiona-assistant librarian and librarian with no subcommand list
the current directory.
list [directory] stdout:
Found <N> files in '<directory>':
- <path>
mdoctor list uses the same listing with the prefix
MDoctor: Found <N> files in '<directory>':.
4.1.1. librarian toc
toc [directory] [flags] writes table_of_contents.md in the
target folder. Flags: --recursive-toc, --non-recursive, and
repeatable --exclude REGEX. Depth comes from section 5.1.
A path that is a file or missing exits 1 on stderr and names
librarian toc file <path>. A folder with no markdown prints
no markdown files found on stdout and writes nothing. In
--recursive-toc mode that message is a log line at INFO instead.
toc file <path> writes an in-file TOC in that markdown file.
toc file * does that for every markdown file under the wiki root
found by section 7.3.1. --sectionized forces section numbering for
that run. Status lines:
wrote toc in <path>
toc already up to date in <path>
skipped <path> (<reason>)
generated toc for <N> file(s), skipped <M>
The summary line is bulk mode only. A file with no H1 is
skipped <path> (no H1 heading) and is not rewritten.
4.1.2. librarian move
NOT_IMPLEMENTED for the whole command. Section 7.3.3 is the
contract.
move <source> <target> [--dry-run] moves a file or a folder and
leaves no dead link behind. Each moved markdown file gets its
relative links rewritten, so every link that resolved before the
move still resolves from the new place. Every other markdown file in
the wiki that links to a moved path gets that link rewritten to the
new path.
A <target> that is an existing folder receives <source> under
its own name, the same as mv. Any other <target> is the new
path. Missing parent folders are created.
Stdout, paths with / separators:
moved <source> -> <target>
rewrote <N> link(s) in <path>
unresolved <N> link(s) in <path>
read-only <N> link(s) in <path>
moved <F> file(s), rewrote <L> link(s) in <R> file(s),
<U> unresolved, <K> read-only
rewrote, unresolved, and read-only lines appear only for a
file whose count is above 0, sorted by <path>. <path> is the
file's path after the move. The summary line is always last and is
one line, even though it is wrapped above. With --dry-run, every line starts with [dry-run]
and one space, and nothing is written. A refusal (7.3.3.2.) prints one
Error: ... line on stderr, writes nothing, and exits 1. Success
exits 0.
4.2. mdoctor
No subcommand means chklint ..
chklint [directory] prints the shared report (section 6.1) with
header PyMarkdownlint Violations and exits 0 even when violations
exist.
fix [directory] runs pymarkdown auto-fix in place. Stdout:
PyMarkdownFix: <N> file(s) fixed
- <path>
A pymarkdown API failure prints
Error: pymarkdown fix failed: <error> on stderr and exits 1.
The command does not skip personal/ or raw/.
NOT_IMPLEMENTED chklint and fix also take one markdown file in
place of [directory] (7.4.4.). Today a file prints
Error: '<path>' is not a valid directory. and exits 1.
4.3. fmlint
fiona-assistant fmlint with no subcommand means chklint ..
chklint [directory] prints the shared report with header
Frontmatter Lint Violations and exits 0 even when violations
exist. A missing directory exits 1.
4.4. python-ruff
No subcommand means chklint .. The report header is
Ruff Violations. Exit code is 0 when the ruff process itself
succeeds, including when violations are listed. lint(path, fix=True)
passes --fix to the ruff binary. There is no fix subcommand yet.
4.5. json-lint
No subcommand means chklint .. Header is JSONLint Violations.
chklint [directory] exits 1 when the report contains violations
and exits 0 when it reports no violations. This differs from
mdoctor, fmlint, and python-ruff, which exit 0 either way.
chklint --fix and fix [directory] rewrite indentation and
trailing commas in place, skip personal/ and raw/, and print:
JSONLintFix: <N> file(s) fixed
- <path>
A missing directory on fix prints
Error: '<path>' does not exist. on stderr and exits 1.
4.6. git
Operates on the git repository at the current directory. Timestamps are UTC.
| Command | Stdout on success |
|---|---|
save --description TEXT |
Committed: <full sha> |
snapshot <tag_name> --description TEXT |
Snapshot created: commit=<sha>, tag=<tag> |
restore <tag_name> |
Restored to: <sha> |
clean |
Working tree cleaned. All changes discarded. |
undo |
Undo to: <sha> |
status |
Status: clean or Status: dirty, then git status |
On failure the tool prints Error: <message> and exits 1.
Commit message: <YYYY-MM-DD HH:MM:SS> <description>.
save runs git add --all and commits. A clean tree, including
no untracked files, raises Working tree is clean. Nothing to commit.
snapshot commits, then creates an annotated tag
<YYYY-MM-DD_HH-MM-SS>_<tag_name> with message
Snapshot: <description>.
restore requires a clean tree
(Working tree is dirty. Use 'clean' to discard current edits first.).
It accepts the full tag or the user tag suffix. The latest tag whose
name equals the argument or ends with _<argument> wins. It checks
that commit's tree into the index and working tree and adds a new
commit <timestamp> Restore to <full tag>. History before that
commit stays.
clean requires a dirty tree
(Working tree is already clean. Nothing to discard.), then
git reset --hard HEAD and git clean -fd.
undo requires a clean tree and at least two commits
(Cannot undo: only one commit exists in the repository.), then
git reset --hard HEAD~1.
4.7. wiki
Subcommands of fiona-assistant wiki.
4.7.1. wiki init
fiona-assistant wiki init [directory]. Success stdout:
Successfully initialized llm-wiki directory at: <resolved path>
Rules are section 3.
4.7.2. wiki check-update
fiona-assistant wiki check-update [directory] [--json].
The directory must contain fiona-settings.json, else stderr
Error: Directory '<path>' is not an llm-wiki directory and exit 1.
A missing directory is
Error: Directory not found: <path> and exit 1.
A successful check exits 0 whether or not updates exist.
Human stdout when current:
Wiki is up to date.
When something differs, the lines that apply:
Files to update: <N>
- <relative path> (<current> -> <template>)
Conflicts (owner copy kept): <N>
- <relative path> (<current> -> <template>) -> <update file name>
Directories to add: <N>
- <relative path>
Files to add: <N>
- <relative path>
Total: <N> file(s) need attention
Files skipped (locally modified): <N>
- <relative path>
The version parenthesis appears only when both versions exist.
When the file was compared by hash instead (7.1.2.12.), the
parenthesis is (sha256 <current> -> <template>), each side the
first 8 lowercase hex digits of that SHA-256. The
Conflicts block appears only when a conflict exists (7.1.2.11.).
Total counts updates, conflicts, and additions.
--json prints one JSON object:
{
"files_to_update": [
{
"path": "<path>",
"current_version": "<version or null>",
"template_version": "<version or null>",
"current_sha256": "<64 hex or null>",
"template_sha256": "<64 hex or null>",
"is_settings_file": false
}
],
"conflicts": [
{
"path": "<path>",
"update_path": "<path>",
"current_version": "<version or null>",
"template_version": "<version or null>",
"current_sha256": "<64 hex or null>",
"template_sha256": "<64 hex or null>"
}
],
"files_to_add": [],
"directories_to_add": [],
"files_skipped": [
{"path": "<path>", "reason": "locally modified"}
],
"total": 0,
"has_updates": false
}
4.7.3. wiki update
fiona-assistant wiki update [directory] [-f|--force] [-y|--yes] [--dry-run] [--json].
Without --force and --yes, stdout shows the check-update text
and the prompt Proceed with update? [y/N] followed by a space.
y and yes proceed.
Any other answer, and a non-TTY, exit 1 with stderr
Error: Update requires confirmation. Use --force or --yes to proceed without prompting.
--dry-run prints Dry run - no files will be modified: and the
check-update text, writes nothing, and exits 0.
Success stdout:
Update complete: <U> file(s) updated, <A> added, <C> conflict(s), <S> skipped.
When <C> is not zero, one more line follows:
Merge each <stem>-update<suffix> into its file: run fiona-assistant housekeeping.
--json suppresses the plan and prints:
{
"files_updated": [],
"files_added": [],
"directories_added": [],
"conflicts": [{"path": "<path>", "update_path": "<path>"}],
"files_skipped": [],
"total": 0
}
A confirmed update that had something to report writes
corefiles.json at the wiki root (7.1.2.14.).
check-update and --dry-run do not. A pristine wiki still
writes nothing (7.1.2.5.). A path in
fiona.wiki.update.ignore_files is left unchanged (7.1.2.15.).
Comparison and merge rules are section 7.1.2.
4.7.4. wiki sanity
fiona-assistant wiki sanity [directory] [--json] [--non-interactive].
Requires fiona-settings.json. Exit 0 when every check is clean,
exit 1 otherwise.
Checks, in this order, one thread each: markdownlint,
frontmatter_lint, python-ruff, mdlinter, jsonlint.
Human report:
Wiki Sanity Report
TARGET: <path>
<failing check reports, omitted when clean>
Results:
<name padded>: PASS - <N> violations (MM:SS)
SANITY PASSED (MM:SS)
A failure ends with
Sanity Failed - <N> checks need attention: and one detail line per
failing check. The pass banner carries the total wall time. The
failure verdict does not. Per-check times may overlap and need not
sum to the total. Rows stay in registry order.
--json skips the progress display and prints:
{
"target": "<path>",
"checks": {
"markdownlint": {
"result": 0,
"violation_count": 0,
"duration_seconds": 0.0,
"violations": []
}
},
"total_violations": 0,
"passed": true
}
result is 0 for pass and 1 for fail. Progress display is
section 7.14.
4.7.5. wiki graph
fiona-assistant wiki graph [directory] [-o FILE] [--format html|json] [--include-pattern GLOB] [--exclude-pattern GLOB] [--wikilinks|--no-wikilinks] [--json] [--external-links|--no-external-links] [-f|--force] [--serve [--host HOST] [--port PORT] [--no-open]].
Defaults: output wiki_graph.html in the current directory, format
html, include **/*.md, wikilinks on, external-link nodes off.
--json selects JSON format. Behavior is section 7.1.4.
A path in fiona.wiki.graph.ignore_files is not a node
(7.1.4.20.). The shipped pattern */table_of_contents.md
also matches table_of_contents.md at the scan root.
NOT_IMPLEMENTED --serve runs a local live view instead of
writing once (7.1.4.19.). --host, --port, and --no-open
are accepted only with --serve. NOT_IMPLEMENTED -f/--force
overwrites an existing output file without the prompt of
7.1.4.5.9. (7.1.4.5.9.1.).
4.7.6. wiki ingest
The contract is section 7.1.5.
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]
<source> is an http:// or https:// URL, or a local file path.
--wiki is the wiki root and defaults to .. It must contain
fiona-settings.json, else stderr
Error: Directory '<path>' is not an llm-wiki directory and exit 1.
<source> and --pending are mutually exclusive, and one of them is
required. argparse reports a violation and exits 2.
--origin URL names the URL a local file was saved
from (7.1.5.2.9.).
Human stdout on success, the lines that apply, in this order:
Fetched: <url> (<media type>, <N> bytes)
Archived: <raw path>
Archived: <raw path> (already archived, sha256 <first 12 hex>)
Duplicate: <page path> already cites this source.
Wrote: <page path> (converter <name>, conversion <complete|partial>)
Warning: <text>
Next: refine <page path>, then set status: refined.
Fetched: appears only for a URL. One Warning: line per warning.
With no converter, or a failed conversion, the raw copy stays and
stdout ends with:
No converter for <media type>. Convert <raw path> by hand.
--pending stdout:
Raw pages: <N>
- <page path> (<first sources entry>)
--json prints one object and nothing else on stdout. Paths are
relative to the wiki root and use /:
{
"source": "<argument as given>",
"origin": "<url, or the file path: wiki-relative inside the wiki>",
"origin_kind": "url",
"media_type": "application/pdf",
"raw_path": "raw/papers/<slug>.pdf",
"raw_reused": false,
"sha256": "<64 lowercase hex>",
"duplicate_page": null,
"page_path": "wiki/sources/<slug>.md",
"converter": "pdf",
"conversion": "complete",
"status": "raw",
"warnings": [],
"dry_run": false
}
origin_kind is url or file. With no page, page_path and
converter are null and conversion is none. duplicate_page
is the page that already cites the matching raw copy, else null
(7.1.5.3.5.). --pending --json
prints {"pending": [{"page_path": ..., "sources": [...], "origin": ...}], "total": <N>}.
NOT_IMPLEMENTED Once staging is built, every page path above is
refine/<rel> (7.1.5.15.2.).
| Exit | Meaning |
|---|---|
| 0 | Raw copy archived. A page was written, --raw-only was set, or a page already cites the same bytes. |
| 1 | Error on stderr. Nothing written under the wiki. |
| 2 | argparse usage error. |
| 3 | Raw copy archived. No page: no converter, or conversion failed. |
| 4 | The URL needs a login (7.1.5.2.8.). Error on stderr. Nothing written under the wiki. |
Errors, each on stderr with exit 1:
Error: Source not found: <path>
Error: Source not found: <path> (moved to <raw path> by an earlier ingest)
Error: Source is a directory: <path>
Error: Unsupported URL scheme: <scheme>
Error: Download failed: <url>: <reason>
Error: Download exceeds <N> bytes: <url>
Error: --raw must stay inside raw/: <value>
Error: --raw cannot be used on a file already under raw/: <path>
Error: --target must stay inside wiki/: <value>
Error: --target cannot replace <path>
Error: Page exists: <path>. Use --force to replace it.
Error: --origin needs a local file: <source>
Error: --origin must be an http or https URL: <value>
A URL that needs a login prints two lines on stderr and exits 4 (7.1.5.2.8.):
Error: Authentication required: <url>: <reason>
Next: save it into ingest/, then run: wiki ingest <file> --origin <url>
The Next: line names the command without the fiona-assistant
prefix so it fits one line. The agent fills <file> with the path
it saved (7.1.5.14.).
A failed conversion prints Error: Conversion failed: <converter>: <reason> on stderr and exits 3, not 1, because the raw copy stays.
NOT_IMPLEMENTED The (moved to ...) form is 7.1.5.2.7..
4.7.7. wiki search
NOT_IMPLEMENTED The contract is section 7.1.6.
fiona-assistant wiki search <keyword> [<keyword> ...] [--wiki DIR]
[--all-words] [--case-sensitive] [--include GLOB] [--json]
--wiki is the wiki root and defaults to .. It must contain
fiona-settings.json, else stderr
Error: Directory '<path>' is not an llm-wiki directory and exit 1.
At least one keyword is required, else argparse exits 2. A quoted
phrase such as "agent harness" is one keyword.
Human stdout, one line per matching line, then one summary line:
<path>:<line>: <text>
... <N> more matches. Narrow the keywords or raise max_results.
Matches: <N> lines in <F> files
<path> is relative to the wiki root and uses /. <line> starts
at 1. The path:line: form is the one grep prints, so editors and
terminals open it as a link. The ... more matches line appears
only when the result limit cut the list.
--json prints one object and nothing else on stdout:
{
"keywords": ["harness"],
"matches": [
{"path": "wiki/sources/agent-harness.md", "line": 44,
"text": "... how LangSmith agent harness works ...",
"columns": [21]}
],
"total": 1,
"files": 1,
"truncated": false
}
text is the shortened text of 7.1.6.4. columns holds the
1-based column of each match in the full line. total counts
every matching line, including those past the limit.
| Exit | Meaning |
|---|---|
| 0 | Search ran. Zero matches is still exit 0. |
| 1 | Error on stderr. |
| 2 | argparse usage error. |
4.8. housekeeping
fiona-assistant housekeeping [directory] [--json]. One call runs
the wiki maintenance routine and tells an LLM what to fix. The
directory must contain fiona-settings.json, else stderr
Error: Directory '<path>' is not an llm-wiki directory and exit 1.
A missing directory is Error: Directory not found: <path> and
exit 1. The steps and their rules are section 7.2.
Human stdout:
Housekeeping Report
TARGET: <path>
[<STATUS>] <step>: <summary>
- <detail>
Next steps:
- <action>
HOUSEKEEPING PASSED
One [<STATUS>] block per step, in step order. <STATUS> is
PASS, WARN, or FAIL. Detail lines appear only when the step
has details. Next steps: appears only when a step has an action.
The last line is HOUSEKEEPING PASSED, or
HOUSEKEEPING FAILED - <N> step(s) need attention: <names> with
the failing step names joined by a comma and a space.
--json prints one object and nothing else on stdout. Paths are
relative to the wiki root and use /:
{
"target": "<path>",
"steps": [
{
"name": "merge",
"status": "FAIL",
"summary": "1 update file(s) wait for a merge",
"details": ["AGENTS-update.md -> AGENTS.md"],
"next": ["Merge AGENTS-update.md into AGENTS.md ..."]
}
],
"passed": false
}
| Exit | Meaning |
|---|---|
| 0 | No step is FAIL. WARN steps may exist. |
| 1 | A step is FAIL, or the directory is not a wiki. |
4.9. Repository runners
python scripts/run_tests.py runs pytest with --color=no and a
temporary JUnit XML report (junit_family=xunit1). The child
process receives the repository src directory on PYTHONPATH,
joined with os.pathsep.
python scripts/run_sanity.py [--non-interactive] runs, in order:
pytests, markdownlint, ruff, frontmatter_lint,
pycustomlint, jsonlint. Same progress display, result table, and
verdict shape as wiki sanity, with label Running Sanity and an
extra untimed coverage: row under pytests. Details are section 7.14.
5. Settings Schema
Two files. fiona-settings.json ships in the template and marks a
wiki root. scripts/settings_dev.json is repository tooling only and is
not copied into a wiki.
5.1. fiona-settings.json
Absent file: pymarkdown uses its own defaults; other tools use the defaults in the table. A typo in a pymarkdown rule id or property name is accepted and has no effect. Confirm a new pymarkdown setting by its effect on a scan. TOC file settings reject unknown keys and bad types with exit 1 and the key name.
Shipped document (logical content; wiki init copies the file):
{
"markdown": {
"pymarkdown": {
"extensions": ["front-matter"],
"respect_gitignore": true,
"md025": {"front_matter_title": "no-match"},
"md013": {"line_length": 100, "code_blocks": false, "tables": false},
"md060": {"enabled": false}
},
"frontmatter": {
"ignore_rules": [],
"ignore_file": [],
"respect_gitignore": true
},
"toc_generator": {
"max_depth_from_file": 3,
"max_depth_from_dir": null,
"file": {
"min_heading": 2,
"max_heading": 6,
"sectionize": false,
"ignore_files": [],
"*/rules.md": {"max_heading": 2}
}
}
},
"json": {
"indent": "space",
"indent_len": 2,
"trailing_commas": false,
"require_key_order": false,
"check_duplicate_keys": true,
"extensions": [".json"]
},
"python": {"ruff": {}},
"fiona": {
"log_level": "INFO",
"file_log_level": "INFO",
"file_log_location": "fiona.log",
"llm-wiki": {"ignore_files": []},
"wiki": {
"graph": {
"show_external_links": false,
"subtitle": {"enabled": true},
"show_legend": true,
"theme": "night-sky",
"show_arrows": false,
"show_source": true,
"show_glow": true,
"show_link_card": true,
"first_fit_ms": 12000,
"hover_link_tail_chars": 12,
"simplify_external_links": false,
"consolidate_external_links": false,
"consolidate_external_links_depth": 0,
"consolidate_external_links_max_char": 8,
"ignore_files": ["*/table_of_contents.md", "*/README.md", "*/AGENTS.md"]
},
"update": {
"ignore_files": ["corefiles.json"]
}
}
}
}
| Key | Type | Default when absent | Consumer |
|---|---|---|---|
markdown.pymarkdown.extensions |
list of strings | none enabled | mdoctor |
markdown.pymarkdown.respect_gitignore |
bool | false | mdoctor |
markdown.pymarkdown.<rule>.<prop> |
bool, int, or str | pymarkdown default | mdoctor |
markdown.pymarkdown.path_rule_exemptions |
list of {path, rules} |
[] |
wiki sanity markdownlint |
markdown.frontmatter.required_fields |
list of strings | ["name", "version"] |
fmlint |
markdown.frontmatter.type_requirements |
object of lists | {} |
fmlint |
markdown.frontmatter.enabled |
bool | true | fmlint |
markdown.frontmatter.ignore_rules |
list of codes | [] |
fmlint |
markdown.frontmatter.ignore_file |
list of globs | [] |
fmlint |
markdown.frontmatter.respect_gitignore |
bool | true | fmlint |
markdown.toc_generator.max_depth_from_file |
int | unlimited (0 or absent) |
folder TOC |
markdown.toc_generator.max_depth_from_dir |
int or null | unlimited | folder TOC |
markdown.toc_generator.file.min_heading |
int >= 2 |
2 | in-file TOC |
markdown.toc_generator.file.max_heading |
int >= min |
6 | in-file TOC |
markdown.toc_generator.file.sectionize |
bool | false | in-file TOC |
markdown.toc_generator.file.ignore_files |
list of globs | [] |
in-file TOC |
markdown.toc_generator.file.<glob> |
object of file keys | none | per-file override |
json.indent |
"space" or "tab" |
"space" |
json-lint |
json.indent_len |
int | 2 | json-lint |
json.trailing_commas |
bool | false | json-lint |
json.require_key_order |
bool | false | json-lint |
json.check_duplicate_keys |
bool | true | json-lint |
json.extensions |
list of strings | [".json"] |
json-lint |
json.max_line_length |
int or absent | no line-length check | json-lint |
python.ruff |
object | {} |
reserved, unused |
fiona.log_level |
level name | WARNING |
logging |
fiona.file_log_level |
level name | fiona.log_level |
file log |
fiona.file_log_location |
string or absent | no file log | file log |
fiona.llm-wiki.ignore_files |
list of globs | copy all | wiki init, update |
fiona.wiki.update.ignore_files |
list of globs | [] |
wiki update, housekeeping merge |
fiona.wiki.graph.wikilinks_enabled |
bool | true | wiki graph |
fiona.wiki.graph.max_files |
int | 5000 | wiki graph |
fiona.wiki.graph.show_external_links |
bool | false | wiki graph toggle |
fiona.wiki.graph.subtitle.enabled |
bool | true | wiki graph toggle |
fiona.wiki.graph.show_legend |
bool | true | wiki graph toggle |
fiona.wiki.graph.show_arrows |
bool | true | wiki graph toggle |
fiona.wiki.graph.show_source |
bool | true | wiki graph toggle |
fiona.wiki.graph.show_glow |
bool | true | wiki graph |
fiona.wiki.graph.show_link_card |
bool | true | wiki graph |
fiona.wiki.graph.first_fit_ms |
number | 12000 | wiki graph |
fiona.wiki.graph.hover_link_tail_chars |
int | 12 | wiki graph |
fiona.wiki.graph.theme |
string | night-sky |
wiki graph |
fiona.wiki.graph.simplify_external_links |
bool | false | wiki graph |
fiona.wiki.graph.consolidate_external_links |
bool | false | wiki graph |
fiona.wiki.graph.consolidate_external_links_depth |
int | follow the bool | wiki graph |
fiona.wiki.graph.consolidate_external_links_max_char |
int | 8 | wiki graph |
fiona.wiki.graph.ignore_files |
list of globs | [] |
wiki graph |
fiona.wiki.graph.node_importance_min_point |
int >= 0 |
0 | wiki graph |
fiona.wiki.graph.directory_nodes.min_files |
int >= 0 |
0 (off) | wiki graph |
fiona.wiki.graph.directory_nodes.outside_depth |
int >= 0 |
1 | wiki graph |
fiona.wiki.graph.serve.host |
string | 127.0.0.1 |
wiki graph --serve |
fiona.wiki.graph.serve.port |
int 0..65535 |
8765 | wiki graph --serve |
fiona.wiki.graph.serve.poll_seconds |
number > 0 |
1 | wiki graph --serve |
fiona.wiki.graph.serve.debounce_ms |
int >= 0 |
300 | wiki graph --serve |
fiona.wiki.ingest.timeout_seconds |
number > 0 |
30 | wiki ingest |
fiona.wiki.ingest.max_download_bytes |
int > 0 |
52428800 | wiki ingest |
fiona.wiki.ingest.user_agent |
string | fiona-assistant/<package version> |
wiki ingest |
fiona.wiki.ingest.default_target |
string | sources |
wiki ingest |
fiona.wiki.ingest.raw_categories |
object of strings | {} |
wiki ingest |
fiona.wiki.ingest.login_url_patterns |
list of regex strings | see below | wiki ingest |
fiona.wiki.ingest.html.min_words |
int >= 1 |
4 | wiki ingest |
fiona.wiki.ingest.html.max_link_density |
number 0..1 |
0.5 | wiki ingest |
fiona.wiki.search.max_line_chars |
int >= 20 |
160 | wiki search |
fiona.wiki.search.max_results |
int >= 0 |
200 | wiki search |
Bool pymarkdown properties use set_boolean_property, ints use
set_integer_property, strings use set_string_property, applied as
plugins.<rule_id>.<property>. "enabled": false inside a rule map
disables that rule.
markdown-tables stays off. pymarkdownlnt 0.9.40 raises
BadTokenizationError on list lines that contain pipes, which breaks
sanity on generated contents files. Until that is fixed, table rules
MD055, MD056, MD058, and MD060 do not run. MD060 is also disabled
because pymarkdown's delimiter-width check disagrees with Node
markdownlint compact tables. Project tables use compact style:
one space around cell text, including the delimiter row
(| --- | ------- |).
Graph colors, sizes, and shapes come from section 5.3. If
node_colors, node_radius, or hover is still present here, those
keys override the colorful theme only. Hover radius is
min(current * size_multiplier, max) and returns to the pre-hover
radius when the pointer leaves. subtitle.enabled starts the
Show Subtitles toggle. The
label is the frontmatter name when that field is a non-empty
string, otherwise the filename. show_legend starts the Show
Legend toggle. The default is on. The card sits at the upper
right of the graph. It groups shape, node size and color, and
edge color, so those three are not one mixed list.
The graph command starts from the graph section of the packaged
fiona-settings.json. A fiona-settings.json found by walking up
from the scanned directory replaces the keys it sets. A missing
file still uses that packaged section.
show_arrows starts the Show Arrows toggle. The default is on.
show_source starts the Show Sources toggle. The default is on.
It draws each frontmatter source value as its own node.
show_glow draws the glow on a hovered node, a clicked node,
and a search match. The default is on. show_link_card draws
the hover card beside the node. The default is on. A click
shows the frontmatter card at the upper left, including when
show_link_card is false. first_fit_ms is the first node's
fit, in milliseconds. The shipped value, and the value when
the key is absent or not a positive number, is 12000. See all,
the last node, and a theme change stay at 4200 ms.
hover_link_tail_chars is how many characters of a URL's last
path segment the hover card keeps. The shipped value, and the
value when the key is absent or not a positive number, is 12.
The arrowhead sits on the target end of a visible edge, so the
source file points at the target file. Turning the toggle off
removes the arrowheads. theme names the theme the page opens
on. The shipped value is night-sky. An unknown name also opens
night-sky. simplify_external_links shortens an external
subtitle to the host. The default is off.
consolidate_external_links draws one node per host, named
host/*, when depth is absent. The default of the bool is off.
consolidate_external_links_depth is how many levels to keep.
0 leaves each URL alone. 1 is host/*. 2 is host/a/*.
3 is host/a/b/*. A missing depth follows the bool: true is
1, false is 0. A path part longer than
consolidate_external_links_max_char is .... That limit is
8 when absent or not a positive integer. Turning depth above
0 also shortens the subtitle to the host.
node_importance_min_point is how many different files must
point at a node before the HTML graph draws it. The count is
unique_points (7.1.4.2.3.). 0 turns the filter off and
every node is drawn. A missing key, or a value that is not an
integer of 0 or more, is 0. A positive integer is 7.1.4.16.
and is not built yet. The packaged fiona-settings.json omits
the key until that requirement is built. Absent means 0.
directory_nodes.min_files is how many markdown pages a
directory must hold directly before the HTML graph draws it as
one directory node (7.1.4.18.). 0 turns consolidation off.
directory_nodes.outside_depth is how many hops past a
directory's own pages its view draws (7.1.4.18.5.).
serve.host, serve.port, serve.poll_seconds, and
serve.debounce_ms are the --serve defaults (7.1.4.19.).
A CLI flag wins over these keys. A value that is absent, of the
wrong type, or out of range uses the default in the table.
Both are not built yet. The packaged fiona-settings.json
omits directory_nodes and serve until they are built.
fiona.wiki.ingest is read by section 7.1.5. default_target is a
directory relative to wiki/. raw_categories maps a converter
name to a directory under raw/, such as {"text": "transcripts"}.
A value that is absent, of the wrong type, or out of range uses the
default in the table. The packaged fiona-settings.json omits
fiona.wiki.ingest. Absent keys use the defaults in the table.
html.min_words and html.max_link_density are read by the block
sweep (7.1.5.4.5.6.).
fiona.wiki.search is read by section 7.1.6 and is not built yet.
max_line_chars is the longest <text> a match line prints.
max_results is how many match lines print. 0 prints them all.
A value that is absent, of the wrong type, or out of range uses the
default in the table.
login_url_patterns is read by 7.1.5.2.8.3. A list replaces
the default list, it does not extend it. An entry that does not
compile, or is not a string, is skipped with one warning. A value
that is not a list uses the default list:
[
"/(login|logon|signin|sign-in)\\b",
"/(sso|saml2?|oauth2?|adfs|cas)(/|$)",
"login\\.microsoftonline\\.com",
"j_security_check"
]
A mapping key under toc_generator.file whose name is not one of
min_heading, max_heading, sectionize, ignore_files is an
fnmatch override against the file path relative to the wiki root.
On wiki update, a differing fiona-settings.json is not
rewritten (7.1.2.3.). The template is written beside it as
fiona-settings-update.json. The owner merges that file: start
from the template object. For each user key, if both sides are
objects, merge recursively; otherwise the user value replaces the
template value. New template keys that the user does not set are
kept. Write the result as JSON with indent 2 and a trailing
newline, then delete the update file.
- 5.1.1. Changing
md013.line_lengthchanges the next mdoctor scan with no code change.- acceptance: A line between the old and new limit is clean after the settings change and reported before it.
- 5.1.2.
wiki updateleavesfiona-settings.jsonbyte-for-byte unchanged and writes the template asfiona-settings-update.json.- acceptance:
markdown.pymarkdown.md013.line_lengthset to 120 is still 120 in the owner file afterwiki update --yes, andfiona-settings-update.jsonis the template copy.
- acceptance:
5.2. settings_dev.json
{
"pytests": {"required-coverage": 96},
"progress": {"interval": 3, "expected-seconds": 30}
}
| Key | Default when absent | Meaning |
|---|---|---|
pytests.required-coverage |
(required for sanity) | Minimum total coverage percent |
progress.interval |
3 | Seconds between non-interactive dots |
progress.expected-seconds |
30 | Bar scale for a running check |
- 5.2.1. Coverage below
required-coveragefails sanity when every test passed.- acceptance: Raising the number in this file flips a green run to failed with no code change.
5.3. constellation themes
Themes for the wiki graph live in constellation/. Each theme is
one JSON file. The file name without .json is the theme name.
colorful is complete and listed first. The other names follow
in alphabetical order. Any other theme may omit keys. A missing
key is taken from colorful. A dark object on a theme is the
same kind of partial theme, used when the page is in dark mode.
Each file has a version string (semver). Bump it when that
theme changes. version is not a color key. A theme that omits
it does not take colorful's version.
colorful is a warm paper field. Nodes run from warm gray
through amber to crimson. Edges use that same warm ramp, darker
so a thin line stays visible. Hover, click, and buttons are one
teal, the complement of the amber. Pages are circles and
external links are clouds. night-sky draws
circle pages and star external links on a dark field.
grayscale runs charcoal to near-black on a light field, with
a dark stroke so the pale end still stands off the canvas. Its
dark object is a gray night on a charcoal field, not black.
Sparse nodes stay medium gray. A mid link count is white-yellow.
Many incoming links are a light yellow-orange. dark is a blue-slate night. Nodes
run from slate through white-yellow to a light gold. The page and the canvas
stay blue-gray, not black. professional is a light boardroom
palette: pale blue nodes, a soft blue stroke, light blue
buttons, and a quiet radius.
| Key | Meaning |
|---|---|
background |
Page background |
graph_background |
Graph canvas background |
font_family |
Font for the page |
text_color |
Text on the page and cards |
node_colors.low/mid/high |
Node color from few to many incoming links |
node_stroke |
Outline around a node, or none |
node_radius.min/max |
Smallest and largest node radius, in em. 16 is 1em. Fractions are kept |
subtitle.min_radius |
Label cutoff, a fraction of node_radius.max from 0 to 1 |
subtitle.padding |
Em between the shape and the label, where 16 is 1em. Smaller sits closer |
subtitle.size |
Label font size in em, where 16 is 1em |
subtitle.on_top |
When true, labels paint above every node |
subtitle.outline |
When true, a stroke keeps the label readable over nodes |
subtitle.outline_color |
Stroke color for that outline |
subtitle.outline_width |
Stroke width in em, where 16 is 1em |
edge_colors.low/mid/high |
Edge color from one link to many |
edge_width |
Edge thickness in em, where 16 is 1em. 1 when absent or not positive |
highlight.node_color |
Node color while the pointer is over it |
highlight.edge_color |
Edge color while a node is highlighted |
highlight.size_multiplier |
Radius multiplier while highlighted |
clicked.node_color |
Node color after a click |
orphan.enabled |
When true, orphan nodes use orphan.node_color |
orphan.node_color |
Fill for an orphan node (7.1.4.2.2.) |
buttons.background/text/hover/disabled |
Button colors |
card.background/border |
Cards, legend, and the control bar |
shapes.page |
circle, cloud, star, or folder |
shapes.external |
Shape for an external-link node |
shapes.directory |
Shape for a directory node (7.1.4.18.). folder in colorful |
subtitle_color |
Label under a large node |
version |
Semver of this theme file. Not a color key |
subtitle.padding is 12 when absent. subtitle.size is 11 when
absent or below 1. subtitle.on_top and subtitle.outline are
false when absent. subtitle.outline_width is 3 when absent.
subtitle.outline_color uses graph_background when absent.
A theme that sets only some of these keeps the rest from
colorful.
- 5.3.1. A theme that omits
font_familyuses thecolorfultheme font. The HTML theme control listscolorful,night-sky,grayscale,dark, andprofessional.- acceptance: The resolved grayscale theme font is the colorful theme font. The graph HTML contains a theme select and those names.
- 5.3.2. Subtitle gap, size, stacking, and outline come from the
active theme's
subtitleobject.- acceptance: The resolved grayscale subtitle padding, size,
on_top, and outline matchcolorful. The graph HTML reads those keys from the theme.
- acceptance: The resolved grayscale subtitle padding, size,
- 5.3.3. Each theme is one JSON file in
constellation/. The name is the file stem.colorfulis first in the catalog. The other names follow in alphabetical order. Each file has aversionstring. Filling a theme does not copyversionfromcolorful, in the loader or in the page script.- acceptance: The template has
constellation/colorful.json,constellation/night-sky.json,constellation/grayscale.json,constellation/dark.json, andconstellation/professional.json, and noconstellation-settings.json. Each resolved packaged themeversionequals theversionin its file. A theme object that omitsversionhas noversionafter it is filled fromcolorful.
- acceptance: The template has
- 5.3.4. A
constellation/directory at the wiki, or in a parent, overlays the packaged themes. Each JSON file there overlays the theme of the same name.constellation-settings.jsonin that same directory overlays those files. The nearest directory that has either source wins. A theme file that is not a JSON object is skipped.- acceptance:
constellation/night-sky.jsonsettingbackgroundchanges that key and keeps the packaged page shape. Aconstellation-settings.jsonbeside it replacesbackgroundwith its own value. A file of{does not removecolorful.
- acceptance:
- 5.3.5. A theme can paint orphan nodes in one color. When
orphan.enabledis true, an orphan page (7.1.4.2.2.) is filled withorphan.node_colorinstead of thenode_colorsramp. Hover and click colors still replace it. External-link and source nodes are never orphans. Every packaged theme has anorphanobject withenabledfalse, so the graph looks the same until a theme turns it on.- acceptance: Every resolved packaged theme has
orphan.enabledfalse and anorphan.node_color. A localconstellation/dark.jsonsettingorphan.enabledtrue keeps the packagedorphan.node_color. The graph HTML readstheme.orphan.enabledandtheme.orphan.node_color.
- acceptance: Every resolved packaged theme has
6. Violation Rule Catalog
6.1. Shared Report
Status: Implemented
Custom linters and the ruff wrapper print this shape. Sanity runners
omit the report for a check with zero violations; the Results: row
still shows the count.
<Linter Name> Violations
TARGET: <path>
- DEFINITIONS:
- <code>: <rule_name>, <description>
- FILE: <path>
- <message>
- SUMMARY:
- Total files with violations: <N>
- Total violations: <N>
A clean standalone run that still prints a report uses
- No violations found. in place of the FILE section and still
prints DEFINITIONS and SUMMARY. Headers:
| Tool | Header name |
|---|---|
| mdoctor | PyMarkdownlint |
| fmlint | Frontmatter Lint |
| python-ruff | Ruff |
| pycustomlint | Python Custom Lint |
| mdlinter | Markdown Lint |
| json-lint | JSONLint |
Frontmatter messages omit a line:column prefix. Frontmatter is
always at the start of the file.
- 6.1.1. A report with one violation contains TARGET, DEFINITIONS,
one FILE entry, and SUMMARY, in that order.
- acceptance: The three custom linters and ruff use this order.
6.2. Frontmatter Fields and FML Codes
Status: Implemented
Required on every markdown file: name, version. Required on every
page under wiki/: confidence, llm, contested, and
contradictions. The Fiona skill teaches how to set those four.
fmlint enforces name and version only. All other fields are
optional.
| Field | Required | Rule |
|---|---|---|
name |
yes | Document name. Wiki pages use lowercase and hyphens. |
version |
yes | Semver. Bump when the page is edited. |
title |
no | Human title. |
created |
no | YYYY-MM-DD |
updated |
no | YYYY-MM-DD. Bump when the page is edited. |
type |
no | entity, concept, comparison, query, summary, toc |
tags |
no | Taxonomy tags from wiki/schema.md |
sources |
no | Paths such as raw/articles/source-name.md |
confidence |
wiki pages | trusted, high, medium, low, or zero. The agent sets it on every page under wiki/. fmlint does not enforce it. |
llm |
wiki pages | model is required. reasoning is set when the model reports a level. The agent sets it on every page under wiki/. fmlint does not enforce it. |
contested |
wiki pages | true when a claim on the page is disputed, otherwise false. The agent sets it on every page under wiki/. fmlint does not enforce it. |
contradictions |
wiki pages | Other page slugs that disagree. [] when none. The agent sets it on every page under wiki/. fmlint does not enforce it. |
description |
SKILL.md only | Required on a file whose name is SKILL.md. |
status |
no | raw or refined. wiki ingest writes raw. Only the agent sets refined (7.1.5.10.). |
ingest |
no | Map of provenance written by wiki ingest: origin, media type, SHA-256, size, converter, conversion, warnings (7.1.5.5.3.). |
source_meta |
no | Map of metadata read from the source, such as author and dates. {} when none. |
markdown.frontmatter.type_requirements maps a type value to the
field list required for that type, in addition to the global list.
| Code | Name | Message | Fails when | Passes when |
|---|---|---|---|---|
| FML001 | Frontmatter Parse Error | FML001 - <error> |
YAML between --- markers is invalid |
YAML parses |
| FML002 | Missing Frontmatter | FML002 |
No frontmatter block | A block is present |
| FML003 | Missing Name Field | FML003 |
name absent |
name present |
| FML004 | Missing Description | FML004 |
SKILL.md has no description |
description present |
| FML005 | Invalid Skill Name | FML005 |
SKILL.md name fails ^[a-z0-9-]+$ |
name: python-tdd |
| FML006 | Skill Name Mismatch | FML006 - (expected: <folder>, got: <name>) |
name differs from the parent folder |
folder python-tdd and name: python-tdd |
| FML007 | Missing Version Field | FML007 |
version absent |
version present |
SKILL.md is case-sensitive. FML005 and FML006 apply only to that
filename. Scan skips .gitignore matches when
respect_gitignore is true, ignore_file globs, and read-only
zones.
- 6.2.1. A markdown file with
nameandversionand notitleproduces no FML violation.- acceptance: fmlint on that file reports no violations.
- 6.2.2.
SKILL.mdinpython-tdd/withname: Python TDDis FML005, andname: other-nameis FML006.- acceptance: The report code matches the case above.
- 6.2.3. Every page under
wiki/includesconfidence,llm,contested, andcontradictions. The Fiona skill requires them and states how to choose each value.confidenceistrusted(the user stated it, or it is copied from a cited source),high(more than one source agrees, or one source and no known contradiction),medium(one source, or a synthesis the agent is reasonably sure of),low(inference, thin evidence, or an open gap), orzero(unknown, or not checked).llmis a list whosemodelentry is required: the model that last edited the page, ornonewhen no model wrote it.reasoningis included when that model reports a level.contestedistruewhen any claim on the page is disputed by a source or another page, andfalseotherwise.contradictionslists thenameof each page that disagrees, and is[]when none do. fmlint enforcesnameandversiononly.- acceptance: Fiona skill section 15 marks those four fields required on wiki pages and states the choice rules above.
6.3. MDL Codes
Status: Implemented
mdlinter scans .md files. Fenced code, inline code, links whose
target starts with http://, https://, mailto:, or #, and any
target containing ://, are ignored. Sources under personal/ and
raw/ are skipped. Targets inside those zones are still resolved.
| Code | Name | Message | Fails when | Passes when |
|---|---|---|---|---|
| MDL001 | Dead Link | line <n>: <target> does not exist |
A relative ](target) does not resolve to a file |
The relative file exists |
| MDL002 | Dead Wiki Link | line <n>: [[<target>]] does not resolve to any page |
A [[wikilink]] matches no markdown stem |
A stem matches, case-insensitive |
| MDL003 | Wrapped Table Row | line <n>: table row continues onto the next line; keep each row on one line |
A line starts with |, does not end with |, and the next line is not blank and not a new row. A following line that is only | counts as a continuation |
The row is one line, or the next line is blank or a new row, or the split is inside a fence |
Wikilink syntax: [[page]], [[page#heading]], [[page|alias]].
The lookup key is the text before # or |, compared to markdown
file stems in the wiki, case-insensitive. Markdown links resolve
against the linking file's directory.
- 6.3.1. A link to a deleted file is MDL001 with file, line, and
target. A
[[missing]]wikilink is MDL002.- acceptance: Both codes appear in one wiki that has one of each.
- 6.3.2. A table row split across two lines is MDL003 on the opening
line. The same split inside a fence is clean.
- acceptance: Only the unfenced split is reported.
6.4. PYC Codes
Status: Implemented
pycustomlint scans .py files with the AST, skips .gitignore
matches and read-only zones, and accepts --json for a JSON list of
violation objects.
| Code | Name | Severity | Message | Fails when | Passes when |
|---|---|---|---|---|---|
| PYC001 | Inline Import | error | PYC001 - Inline import at line <n>: <stmt> |
import or from is indented inside a function, class, try, or an if that follows a function or class |
Every import is at column 0, or it sits in a module-level if before the first function or class |
| PYC002 | Import After Code | warning | PYC002 - Import after code at line <n>: <stmt> |
A module-level import follows a non-import statement | Imports are grouped before other module statements |
| PYC003 | Late Declaration | error | PYC003 - Declaration after first function or class at line <n>: <stmt> |
A module-level assignment is at or after the first function or class in the module body | Every module-level assignment is before that first function or class |
- 6.4.1.
import osinside a function is PYC001.- acceptance: The report names the file, the line, and
import os.
- acceptance: The report names the file, the line, and
- 6.4.2. An import inside a module-level
if,elif, orelsethat appears before the first function or class is not PYC001. The same import after that first function or class is PYC001. Atrydoes not get this exception. An import inside a function or class is PYC001.- acceptance:
if os.name == "nt": import msvcrtbefore any function is clean. The sameifafter a function is PYC001 and the message namesimport msvcrt. - acceptance:
try: import osbefore any function is PYC001.
- acceptance:
- 6.4.3. A module-level assignment at or after the first function
or class statement in the module body is PYC003. An assignment
nested inside a function or class is not PYC003. An assignment
before that first function or class, including one inside a
module-level
if, is not PYC003.- acceptance:
SHORT_HASH_LENGTH = 8after a function is PYC003 and the message namesSHORT_HASH_LENGTH = 8. - acceptance: The same assignment before any function or class is clean.
- acceptance:
value = 1inside a function, andVALUE = 1inside a class, are clean. - acceptance:
VALUE = 1inside a module-levelifbefore any function is clean. The sameifafter a function is PYC003.
- acceptance:
6.5. JSN Codes
Status: Implemented
json-lint parses with the standard json module. Style checks use
section 5.1. Duplicate-key detection uses a parse hook so the last
value does not hide the earlier key.
| Code | Name | Severity | Fails when | Passes when |
|---|---|---|---|---|
| JSN001 | JSON Syntax Error | error | The file is not JSON, including a trailing comma when that is a syntax error | json.loads succeeds |
| JSN002 | Indentation Error | error | Indent differs from indent / indent_len |
Indent matches |
| JSN003 | Trailing Comma | error | A trailing comma is present and trailing_commas is false |
No trailing comma, or the setting allows them |
| JSN004 | Duplicate Keys | error | An object repeats a key and check_duplicate_keys is true |
Keys are unique |
| JSN005 | Key Order | warning | require_key_order is true and keys are not sorted |
Keys are sorted, or the setting is false |
| JSN006 | Line Too Long | warning | max_line_length is set and a line exceeds it |
The key is absent, or every line fits |
- 6.5.1. A file with a missing comma reports JSN001 with line and
column. A file with duplicate keys reports JSN004.
- acceptance: Both cases name the file and the code.
- 6.5.2. Four-space indent against
indent_len: 2is JSN002.json-lint fixrewrites it to two spaces.- acceptance: The fixed file is clean on the next
chklint.
- acceptance: The fixed file is clean on the next
6.6. Base Linter Contract
Status: Implemented
- 6.6.1. Shared behavior for fmlint, pycustomlint, mdlinter, and
json-lint.
- 6.6.1.1. Recursive file collection by extension.
- 6.6.1.2.
.gitignoreand read-only-zone skipping. - 6.6.1.3. Settings load from
fiona-settings.json. - 6.6.1.4. A violation record has filepath, line, column, code, message, rule id, and severity, plus a dict form for JSON.
- 6.6.1.5. Report assembly follows section 6.1. The header is the linter name.
- 6.6.1.6. The CLI is
chklint [directory]and defaults to..
- 6.6.2. A new rule is a new checker used by one linter. It does
not require an edit to the shared collector. Codes are unique:
FML,MDL,PYC,JSN, plus pymarkdownMDcodes and ruff codes.- acceptance: Existing FML and PYC tests still pass after a new MDL checker is registered.
7. Feature Requirements
7.1. wiki
Requirements for the wiki subcommands.
7.1.1. wiki init
Status: Partially Implemented
Implements sections 3 and 4.7.1.
- 7.1.1.1. Copy is 1:1 aside from
DATE_PLACEHOLDER,ignore_files, and paths matched by the repository.gitignore.- acceptance: A pattern in
ignore_filesomits those paths and copies every other template file. - acceptance: A template file matched by the repository
.gitignoreis not copied.
- acceptance: A pattern in
- 7.1.1.2. Copied markdown keeps
versionand receivescreated/updateddates where the template used the placeholder.- acceptance: After init, those fields match
YYYY-MM-DDfor the UTC day of the run.
- acceptance: After init, those fields match
- 7.1.1.3.
wiki initputs or appends.gitignorefrom the repository.gitignore, pluspersonal/when that pattern is missing. Lines already in the file stay.- acceptance: After init,
.gitignorecontains__pycache__/andpersonal/. A linekeep-mewritten before init is still in the file.
- acceptance: After init,
- 7.1.1.4.
NOT_IMPLEMENTEDThe CLI turns the refusal of 3.2.2. into one stderr line and exit 1 (1.2.7.):Error: Directory '<path>' already contains llm-wiki files: <names>. Run fiona-assistant wiki update to refresh the template.The line is one line, even though it is wrapped here.<names>is the comma-separated list from theFileExistsErrormessage.- acceptance: A second
wiki initexits 1, stderr is exactly that line, and no file changes.
- acceptance: A second
7.1.2. wiki update
Status: Implemented
Implements sections 4.7.2 and 4.7.3.
-
7.1.2.1. Markdown core files are compared as follows. An existing markdown file is never overwritten.
- 7.1.2.1.1. Both sides have
version, and the template version is greater: conflict (7.1.2.11.). Numeric dotted versions compare segment by segment (1.2.0vs1.10.0). Any other string compares as text. - 7.1.2.1.2. The wiki version is greater, or the versions are equal
and the body differs after expanding
DATE_PLACEHOLDERin the template: skip the file and reportlocally modified. - 7.1.2.1.3. Either version is missing: compare SHA-256 (7.1.2.12.). Equal hashes need nothing. Different hashes are a conflict.
- 7.1.2.1.1. Both sides have
-
7.1.2.2. Other core files compare SHA-256 (7.1.2.12.) and update when the hash differs.
-
7.1.2.3.
fiona-settings.jsonuses the hash comparison of 7.1.2.12.. Different hashes are a conflict (7.1.2.11.). The owner's file stays. The template is written asfiona-settings-update.json. The tool does not merge the two.- acceptance: After
wiki update --yes, the owner settings bytes are unchanged andfiona-settings-update.jsonmatches the template.
- acceptance: After
-
7.1.2.4. Missing template directories outside
wiki/and outside read-only zones are created when they hold a file that update may add. User files that are not in the template stay. Read-only zones are never in the update set. -
7.1.2.5. A pristine init reports
Wiki is up to date.andwiki updatewrites nothing.- acceptance: A second check-update still reports up to date.
-
7.1.2.6. An older core markdown file is listed as a conflict. After a confirmed update its bytes are unchanged and its update file matches the template. A locally modified file is listed under skipped and is not overwritten.
- acceptance: The modified file's bytes are unchanged after
wiki update --yes. - acceptance: An
AGENTS.mdat1.0.0against a template at2.0.0keeps its bytes afterwiki update --yes, andAGENTS-update.mdholds the expanded template text.
- acceptance: The modified file's bytes are unchanged after
-
7.1.2.7.
--dry-runprints the plan and leaves the tree unchanged.- acceptance: File hashes before and after a dry run match.
-
7.1.2.8.
--forceand--yesskip the prompt, including on a non-TTY.- acceptance: The command exits 0 on a pipe when
--yesis set and updates exist.
- acceptance: The command exits 0 on a pipe when
-
7.1.2.9. A path under
wiki/is never added, overwritten, or listed as a change, an addition, a skipped file, or a directory to add. A template page underwiki/that is newer than the wiki's copy (7.1.2.1.1. or 7.1.2.1.3.) is listed as a conflict, the same as any other markdown core file.- acceptance: A
wiki/index.mdolder than the template keeps its bytes afterwiki update --yes, andwiki/index-update.mdholds the expanded template text. - acceptance: A
wiki/index.mdnewer than the template, or missing, is absent from the check-update report.
- acceptance: A
-
7.1.2.10. Update skips a path matched by the repository
.gitignoreor by the wiki's.gitignore. Comment lines and blank lines are not patterns. A pattern with no slash matches any path segment. A pattern that ends with/matches that directory and everything under it.- acceptance: A template file
utils/scripts/__pycache__/example.pycis absent from the check-update report. - acceptance: When the wiki
.gitignorelistsexample.py, a driftedutils/scripts/example.pyis left unchanged and is absent from the report.
- acceptance: A template file
-
7.1.2.11. A conflict means the template copy and the owner's copy both exist and the tool must not overwrite the owner. That is a newer markdown file (7.1.2.1.) or a differing
fiona-settings.json(7.1.2.3.). Update yields to the owner: it keeps the file and writes the template beside it. The LLM merges the two during housekeeping (7.2.).- 7.1.2.11.1. The update file sits in the same directory. Its name
is the file stem, then
-update, then the suffix:AGENTS.mdgivesAGENTS-update.md,wiki/schema.mdgiveswiki/schema-update.md, andfiona-settings.jsongivesfiona-settings-update.json. Relative links in the template still resolve from that directory.- acceptance: A conflict on
wiki/schema.mdwriteswiki/schema-update.mdandcorefiles.json, and no other file.
- acceptance: A conflict on
- 7.1.2.11.2. The update file holds the template text with
DATE_PLACEHOLDERexpanded, aswiki initwould write it. An existing update file is replaced with the current template text.- acceptance: A second
wiki update --yesleaves one update file, with the same bytes as the first run on the same day.
- acceptance: A second
- 7.1.2.11.3. Only a confirmed update writes an update file.
check-updateand--dry-runlist the conflict and write nothing.- acceptance: No
*-update.mdexists afterwiki update --dry-run.
- acceptance: No
- 7.1.2.11.4. A conflict clears when the owner's
versionis at least the template's version. The merge sets that version and deletes the update file.- acceptance: After
AGENTS.mdis set to the template version with the owner's body, check-update lists no conflict for it.
- acceptance: After
- 7.1.2.11.1. The update file sits in the same directory. Its name
is the file stem, then
-
7.1.2.12. A file without version control, meaning a markdown file with no
versionon either side or any non-markdown file, is compared by SHA-256. The wiki side and the template side both use the text hash in 7.1.2.13.. The template side expandsDATE_PLACEHOLDERbefore that hash. A binary file hashes its raw bytes.- 7.1.2.12.1. Equal hashes: the file is up to date and is not
listed.
- acceptance: A freshly initialized wiki reports
Wiki is up to date.even when a template file holdsDATE_PLACEHOLDER.
- acceptance: A freshly initialized wiki reports
- 7.1.2.12.2. Different hashes: the report line shows both hashes
where a version pair would go, shortened to 8 hex digits:
(sha256 1a2b3c4d -> 9f8e7d6c).--jsoncarries the full 64-digitcurrent_sha256andtemplate_sha256. A file compared by version hasnullin both.- acceptance: A drifted
utils/scripts/example.pyis listed asutils/scripts/example.py (sha256 <8 hex> -> <8 hex>), and a markdown file with noversionthat differs is a conflict with the same parenthesis.
- acceptance: A drifted
- 7.1.2.12.1. Equal hashes: the file is up to date and is not
listed.
-
7.1.2.13. The SHA-256 of a UTF-8 text file is the digest of that text after every
\r\nand every lone\ris folded to\n, then encoded as UTF-8. Two text files that differ only in line endings are equal. A file that is not valid UTF-8 hashes its raw bytes, with no folding.- acceptance:
fiona-settings.jsonsaved with CRLF against a template saved with LF, with the same characters, is not a conflict and is absent from the check-update report.
- acceptance:
-
7.1.2.14. A confirmed
wiki updatethat had a file to update, add, or conflict writescorefiles.jsonat the wiki root.check-updateand--dry-rundo not write it. A pristine wiki writes nothing (7.1.2.5.). The file is not part of the template and is never itself an update, a conflict, an addition, or a merge candidate (7.2.3.). Only this command writes it. It is one JSON object:{ "files": { "<relative posix path>": { "version": "<owner version or null>", "template_version": "<template version or null>", "sha256": "<64 hex>", "template_sha256": "<64 hex>", "date": "YYYY-MM-DD" } } }Each entry is a core file the update compared, using that file's bytes after the update.
dateis the UTC day the entry was written. A later check does not list a core file while its owner version, template version, owner hash, and template hash still match that entry, including a second update on the same day. The date does not expire the entry. A missing record, or a record that is not this object, acknowledges nothing. When the owner file or the template changes, the file is listed again.- acceptance: After
wiki update --yeson a driftedfiona-settings.json,corefiles.jsonnamesfiona-settings.jsonwithversionnull, both 64-digit hashes, and the UTC date. A second check-update does not list that file. Editing the owner file lists it again. - acceptance:
wiki update --dry-rundoes not createcorefiles.json.
- acceptance: After
-
7.1.2.15.
fiona.wiki.update.ignore_filesis a list of glob patterns in the wiki'sfiona-settings.json. A path that matches is not an update, a conflict, an addition, or a merge candidate.wiki updatedoes not copy or replace it. A missing key is an empty list. A value that is not a list of strings raisesValueErrorwith the textfiona.wiki.update.ignore_files must be a list of strings. The shipped list iscorefiles.json. That path is the record in 7.1.2.14. and stays out of the candidate set even when the list omits it. A confirmed update still writes the record.- acceptance: A drifted
utils/scripts/example.pywhose path is in the list is absent from check-update and unchanged afterwiki update --yes. - acceptance: A template
corefiles.jsonthat differs from the wiki copy is absent from check-update, andwiki update --yesleaves the wiki copy unchanged when nothing else needs an update. - acceptance: A non-list
ignore_filesmakes check-update raiseValueErrorwith that text.
- acceptance: A drifted
7.1.3. wiki sanity
Status: Implemented
Implements section 4.7.4. Markdown lint uses the wiki's own
fiona-settings.json. Dead links are MDL001 and MDL002 inside
mdlinter, not a separate check. New checks are added by registering
another (name, runner) pair in the wiki sanity list.
- 7.1.3.1. A clean wiki exits 0. Any violation exits 1.
- acceptance: One dead link makes
passedfalse in--jsonand produces a non-zero exit.
- acceptance: One dead link makes
- 7.1.3.2.
--jsonoutput contains only JSON.- acceptance: The stdout of a
--jsonrun parses withjson.loadsand contains no ANSI sequences.
- acceptance: The stdout of a
- 7.1.3.3. Human output uses the progress display in 7.14.2.
with label
Running Wiki Sanity.- acceptance: A piped run prints that label and dots, and no ANSI escapes.
- 7.1.3.4.
markdown.pymarkdown.path_rule_exemptionsomits matching markdownlint hits from wiki sanity only. Each entry haspath(glob relative to the wiki root) andrules(pymarkdown rule ids). Other sanity checks still scan those paths.- acceptance: A file under
tasks/with an MD013 violation and{"path": "tasks/**", "rules": ["MD013"]}in settings reports zero markdownlint violations; without the entry it fails.
- acceptance: A file under
7.1.4. wiki graph
Status: Partially Implemented
7.1.4.16., 7.1.4.17., 7.1.4.18., and 7.1.4.19. are planned. Every other requirement in this section is built.
The renderer is D3 v7, loaded from https://d3js.org/d3.v7.min.js,
with the visualization embedded in one HTML file. vis.js is not
used.
- 7.1.4.1. The parser extracts links as follows.
- 7.1.4.1.1. Markdown links
[text](path), including./and../, resolve against the source file and are stored relative to the wiki root. A path without an extension is treated as.md. - 7.1.4.1.2. Wikilinks
[[file]]and[[dir/file]]are parsed when wikilinks are enabled. - 7.1.4.1.3. External URLs (
http://,https://,ftp://, and any://) are recorded. The HTML graph includes each URL as a node. JSON lists them in metadata only with--external-linksorexternal_linksin settings. - 7.1.4.1.4. A link whose target file is missing is recorded as broken and does not abort the run.
- 7.1.4.1.1. Markdown links
- 7.1.4.2. The graph is built as follows.
- 7.1.4.2.1. A node is a markdown file. An edge is one or more links from source to target. Weight is the link count. Each markdown node stores that file's full frontmatter object.
- 7.1.4.2.2. An orphan has in-degree 0 and out-degree 0.
- 7.1.4.2.3. Each node stores
unique_points,total_points, andlink_score.unique_pointsis how many different files point at the node.total_pointsis the sum of those weights. One source with weight w scores2 * (1 - 0.5^w). Ten links from one file score less than two files that each link once.
- 7.1.4.3.
--format jsonand--jsonemit this object.
{
"metadata": {
"wiki_root": "<path>",
"file_count": 1,
"link_count": 0,
"generated_at": "<UTC ISO-8601>"
},
"nodes": [
{
"id": "wiki/a.md",
"name": "a.md",
"in_degree": 0,
"out_degree": 0,
"unique_points": 0,
"total_points": 0,
"link_score": 0,
"frontmatter": {"name": "A", "version": "1.0.0"}
}
],
"edges": [
{"source": "wiki/a.md", "target": "wiki/b.md", "weight": 2}
],
"orphans": ["wiki/a.md"]
}
- 7.1.4.4. When external URLs were collected,
metadataalso hasexternal_links_count(total occurrences) andexternal_links(unique URL strings). - 7.1.4.5. HTML behavior.
- 7.1.4.5.1. One self-contained file. The layout fills the
viewport and follows resize. The page script is
templates/graph_physics.js. Generation pastes that file into the page. The saved HTML does not request it separately.- acceptance: Generated HTML contains
function frameNodesand does not contain the paste marker.
- acceptance: Generated HTML contains
- 7.1.4.5.2. Node radius scales with
link_scorefrommintomaxin section 5.3.minandmaxare lengths in em, where 16 is 1em, and may be fractions. The drawn radius keeps that fraction, so the sizes between min and max are not snapped to a whole unit. Color interpolates low to mid over the first half oflink_scoredivided by the max score, then mid to high. A score of 0 uses the low color and the min radius. Two files that each link once outrank one file that links ten times. - 7.1.4.5.3. Edge thickness is
edge_widthfrom the active theme, in em, where 16 is 1em. It is 1 when that key is absent or not a positive number. Changing the theme uses that theme's width. Color runs from gray (weight 1) through yellow to red (maximum weight). - 7.1.4.5.4. Hover: the node uses the hover color and the capped
larger radius. Connected edges use the hover edge color.
Other visible edges dim. Leaving the node restores its previous
radius and color and restores the dimmed edges. Hover does not
clear a click highlight. While both are active, edges of the
hovered node and edges of the clicked node stay highlighted.
Hover fixes the node in place the same way a click does.
Leaving the node releases it, unless that node is the clicked
one. A card appears beside the node. A line with an arrow
points from the card to the node, the same way an edge points
at its target. The card has two lines. The first line is the
node name. The second line is
unique points:total points:in:out. A page name stays as the filename. Anhttporhttpslink drops the scheme. A path with more than one segment showshost/.../last. When that last segment is longer thanhover_link_tail_chars, the card showshost/...plus the last that many characters, with no slash before them. Width follows the longer line. Height follows the two lines. The card is a body in the layout. A link keeps it near the node. It repels other nodes, and they repel it. The card stays inside the graph. Leaving the node hides that card. It does not hide a click card. Hover uses that glow whenshow_glowis true or absent.show_glowfalse draws no glow on hover, click, or a search match. The hover card is shown whenshow_link_cardis true or absent.show_link_cardfalse draws no hover card. It does not change the click card. - 7.1.4.5.5. Single click toggles a persistent highlight and
shows that file's frontmatter card at the upper left of the
graph. This card is not the hover card. It lists every
frontmatter field and its value, then unique points, total
points, in-degree, and out-degree. A file with no frontmatter
shows an empty field list. Another node replaces the card.
Empty space hides it. Hover does not.
show_link_carddoes not hide it. The clicked node carries the same glow as a search match whenshow_glowis true or absent. Clearing the highlight removes that glow. A node that is still a search match keeps the glow when glow is on. The clicked node is fixed where it is. No other node is fixed. Connected nodes keep moving under the simulation, so their edges follow. Clearing the highlight releases the node. Dragging that node leaves it fixed at the drop point. - 7.1.4.5.6. Double click opens the markdown file. A double click on a directory node opens that directory's view instead (7.1.4.18.4.).
- 7.1.4.5.7. Search highlights matching nodes in light blue at
1.5 times radius (capped at max), shows neighbors in gray, and
hides nodes that are not reachable from a match. A match also
carries a glow when
show_glowis true or absent. Neighbors and a cleared search do not.show_glowfalse draws no glow. - 7.1.4.5.8. A checkbox toggle labeled "Show Orphan Nodes" shows or hides orphans. It starts checked. The label does not change.
- 7.1.4.5.9. Overwrite of an existing output file asks for
confirmation on a TTY.
- 7.1.4.5.9.1.
NOT_IMPLEMENTED-f/--forceskips that prompt. Without a TTY and without--force, the file is still overwritten and oneWARNINGrecord names it. The housekeeping graph step (7.2.6.) passes--force, becausewiki_graph.htmlis the one file it owns (7.2.7.), and logs that overwrite atINFO.- acceptance: Housekeeping on a wiki that already has
wiki_graph.html, atLOG_LEVEL=WARNING, writes noOverwritingline on stderr.
- acceptance: Housekeeping on a wiki that already has
- 7.1.4.5.9.1.
- 7.1.4.5.10. Files above
max_filesare skipped after a warning. The firstmax_filesfiles are drawn. - 7.1.4.5.11. The run completes in under 10 seconds for 1000 files on a current developer machine.
- 7.1.4.5.12. A checkbox toggle labeled "Show External Links"
shows or hides external-link nodes and their edges. It starts
checked when
show_external_linksin section 5.1 is true, and unchecked when that key is absent or false. The label does not change. When it starts checked, those nodes and edges are drawn on the opening fade. A click is not required. An external node is the text cloud character. A page node stays a circle. - 7.1.4.5.13. A checkbox toggle labeled "Show Subtitles" shows or
hides labels under nodes. It starts checked when
subtitle.enabledin section 5.1 is true or absent, and unchecked when that key is false. The label does not change. A node shows its label when its drawn radius is at leastsubtitle.min_radiusfrom the active theme times that theme'snode_radius.max. The fraction is 0.5 when absent, and a value outside 0 to 1 is clamped. Changing the theme uses that theme's fraction and max. The text is the frontmatternamewhen that field is a non-empty string, otherwise the filename. The label sits under the shape. The gap issubtitle.paddingem from the active theme, where 16 is 1em, 12 when absent. A smaller number sits closer. The font size issubtitle.sizeon that same scale, 11 when absent or below 1.subtitle.on_toptrue draws every label after the nodes, so another node does not cover it. Absent or false keeps the label inside its node.subtitle.outlinetrue strokes the letters withsubtitle.outline_widthon that same scale, 3 when absent, insubtitle.outline_color. Absent color usesgraph_background. Absent or false draws no stroke. Changing the theme applies that theme's subtitle settings. - 7.1.4.5.14. A checkbox toggle labeled "Show Legend" shows or
hides a card at the upper right of the graph. It starts
checked when
show_legendin section 5.1 is true or absent, and unchecked when that key is false. The label does not change. The card has three groups. Shape shows a page and an external link in the text color. Nodes are growing circles: few, some, and many files pointing here. Edges are lines: linked once, a few times, and many times. Node circles use the theme node colors. Edge lines use the theme edge colors. - 7.1.4.5.15. A select labeled "Theme" lists every theme from
section 5.3 and starts on
themefrom section 5.1. That name isnight-skywhen the key is absent. Choosing a theme updates the page background, font, buttons, cards, node colors, node sizes, edge colors, highlight colors, the clicked-node color, and node shapes. Choosing a theme also runs the See all fit, so the shown nodes are centered again. The grayscale dark-mode switch runs that fit too. The theme applied at load does not. A missing theme key usescolorful.grayscaleuses itsdarkobject when the page is in dark mode. - 7.1.4.5.16. A checkbox toggle labeled "Show Arrows" draws or
hides an arrowhead on each visible edge. It starts checked
when
show_arrowsin section 5.1 is true or absent, and unchecked when that key is false. The label does not change. The arrowhead meets the target shape. The source file points at the target file. The arrow uses that edge's color. A hidden edge has no arrowhead. - 7.1.4.5.17.
simplify_external_linkssets an external node's subtitle to its host. A leadingwww.is dropped. The node stays one per URL.consolidate_external_linksmerges URLs with the same host into one node whose id ishost/*whenconsolidate_external_links_depthis absent. Depth0leaves each URL alone, even when the bool is true. Depth1ishost/*. Depth2ishost/a/*. Depth3ishost/a/b/*. A leadingwww.is dropped from the host. A path part longer thanconsolidate_external_links_max_charcharacters is.... The limit is 8 when absent. A part of that length stays. Size and color followlink_scorein section 7.1.4.2.3. When depth is above 0, simplify is on even if its key is false. The bool defaults to false. A double click openshttps://host/plus the real path parts before the first..., with a trailing slash.- acceptance:
https://www.domain.com/abcandhttps://domain.com/acdfrom two files become one nodedomain.com/*with subtitledomain.comandlink_score2 when consolidate is true and depth is absent. With only simplify, both URLs remain and each subtitle isdomain.com. Depth2mergeshttps://domain.com/abc/oneandhttps://domain.com/abc/twointodomain.com/abc/*and leaveshttps://domain.com/zzz/oneasdomain.com/zzz/*. Depth3nameshttps://domain.com/a/b/casdomain.com/a/b/*and openshttps://domain.com/a/b/.https://domain.com/abcdefghij/b/cat depth3isdomain.com/.../b/*.
- acceptance:
- 7.1.4.5.18. A refresh puts every toggle, the theme select, and
the search box back to the values in section 5.1. The browser's
saved form state does not keep the previous choice.
- acceptance: The page sets each control again on
pageshow.
- acceptance: The page sets each control again on
- 7.1.4.5.19. A checkbox toggle labeled "Show Sources" shows or
hides nodes built from the frontmatter
sourcekey, and the edges from the page to those nodes. It starts checked whenshow_sourcein section 5.1 is true or absent, and unchecked when that key is false. The label does not change. A string is one node. A list of strings is one node per entry. A blank string is skipped. Any other value is skipped. The node is a cloud, the same shape as an external link. Its id is that string. Two pages with the same string share one node. A double click opens the string when it contains://.- acceptance:
source: https://example.com/rules.mdadds one cloud node and one edge from that page. A list of two URLs adds two nodes.source: 12adds none.
- acceptance:
- 7.1.4.5.1. One self-contained file. The layout fills the
viewport and follows resize. The page script is
- 7.1.4.6. Layout constants live at the top of the HTML template so they can be tuned without hunting through the script.
| Constant | Value | Role |
|---|---|---|
LINK_STRENGTH |
0.4 | Spring along an edge; neighbors follow a dragged node |
BASE_LINK_DISTANCE |
80 | Rest length of an edge |
LINK_DISTANCE_PER_DEGREE |
0 | Distance does not grow with degree |
CHARGE_STRENGTH |
-140 | Repulsion that spreads the cloud |
CHARGE_DISTANCE_MIN |
24 | Near distance for repulsion |
CHARGE_DISTANCE_MAX |
500 | Far cutoff for repulsion |
NODE_ATTRACTION_STRENGTH |
0 | Extra attraction is off |
CENTER_STRENGTH |
1 | Each tick places the centroid on the viewport center |
GRAVITY_STRENGTH |
0.05 | Per-node pull toward the viewport center |
COLLIDE_STRENGTH |
1 | Overlap prevention |
BASE_COLLIDE_RADIUS |
6 | Gap around the hitbox |
HITBOX_SCALE |
1.25 | Collision circle versus the drawn radius |
EDGE_PADDING_MULTIPLIER |
0 | Degree does not add collide radius |
CANVAS_MARGIN |
56 | Border band that pushes a node inward |
CANVAS_MARGIN_STRENGTH |
0.35 | Strength of that inward push |
ALPHA_DECAY |
0.018 | How fast the simulation cools |
ALPHA_MIN |
0.001 | Floor before the layout rests |
VELOCITY_DECAY |
0.22 | Low damping so motion glides |
FLOAT_AMPLITUDE |
2 | Idle drift, in em where 16 is 1em |
FLOAT_SPEED |
0.0007 | How fast that drift cycles |
- 7.1.4.7. Nodes start in a small disk around the viewport center
and expand under repulsion. They fade in by a breadth-first walk
from the highest in-degree node, highest connectivity first.
d3.forceCenterkeeps the centroid on the viewport center.d3.forceXandd3.forceYadd center gravity so outliers drift back. Both targets follow resize. The tick does not write a canvas-edge clamp back into node coordinates. A margin force adds inward velocity only while a node is insideCANVAS_MARGINof the border, and it skips a node that is pinned. The hitbox isHITBOX_SCALEtimes the drawn radius, plus a fixed gap, so a large node keeps clear of its neighbors. Each tick then pushes any covering pair apart until the drawn circles, plus that gap, no longer cover. An edge's rest length is at least the two hitboxes added together. Degree does not add padding, so a hub is not shoved into the border. An unpinned node then drifts at mostFLOAT_AMPLITUDEon that em scale, and its edges follow, so it looks like it is floating. A pinned or dragged node does not drift. The view eases toward every shown node over about 4200 ms, with 4em of padding. That is the same fit as the button labeled "See all". The first node usesfirst_fit_msinstead, so that opening zoom is slower. It runs when the first node fades in, and again when the last node fades in. A fit that is already moving keeps its speed and aims at the new bounds. A second See all does not stop the zoom. It also runs when the theme changes. The scale can go below 0.15 when that is what fits the cloud, and it stays at most 6. Hidden external links and hidden orphans are left out. A later wheel zoom, background drag, or node drag keeps the view the user set. Wheel zoom and background drag pan the view. Dragging a node reheats the simulation; releasing it lets the springs and gravity settle. - 7.1.4.8. The output path must be writable. A failure is an error message and a non-zero exit.
- 7.1.4.9. A wiki with one relative link and one wikilink produces
two edges, and a file with neither is listed in
orphans.- acceptance: The JSON
edgesweights match the link counts.
- acceptance: The JSON
- 7.1.4.10.
--no-wikilinksdrops wikilink edges and keeps markdown links.- acceptance: The wikilink target is absent from
edges.
- acceptance: The wikilink target is absent from
- 7.1.4.11. Opening the HTML in a current browser shows the graph,
hover, click highlight, search, and the orphan toggle.
- acceptance: A node hover changes its color to the hover color and restores the previous radius on exit.
- 7.1.4.12. JSON and HTML each store
frontmatteron every markdown node: every YAML field from that file. Missing or invalid YAML is{}and does not abort the run.- acceptance: A file with
name,version, andupdatedhas those three keys on its node. A file with no frontmatter has{}. The click card lists every frontmatter field. The hover card has two lines: the node name, then unique points, total points, in-degree, and out-degree.
- acceptance: A file with
- 7.1.4.13. Repeated links from one file add less to size and
color than links from different files.
- acceptance: One source with weight 10 has
unique_points1,total_points10, andlink_scorebelow 2. Two sources with weight 1 havelink_score2. HTML radius and color dividelink_scorebymaxLinkScore. The hover card's second line includes the unique-point count and the total-point count.
- acceptance: One source with weight 10 has
- 7.1.4.14. The Show Arrows toggle follows
show_arrows.- acceptance: The checkbox is checked when the key is absent
or true, and unchecked when it is false. The HTML defines
marker
edge-arrowand setsmarker-endfrom that toggle.
- acceptance: The checkbox is checked when the key is absent
or true, and unchecked when it is false. The HTML defines
marker
- 7.1.4.15. Graph settings start from the packaged
fiona-settings.jsongraph section. A file found by walking up from the scanned directory replaces the keys it sets. A missing file still uses the packaged section.- acceptance: A scan whose directory and parents have no
fiona-settings.jsonstill appliesshow_legend,show_arrows, andsimplify_external_linksfrom the packaged file.
- acceptance: A scan whose directory and parents have no
- 7.1.4.16.
NOT_IMPLEMENTEDThe HTML graph draws a node when enough files point at it, or when a parent of that node is clicked. The setting isnode_importance_min_pointin section 5.1.- 7.1.4.16.1.
NOT_IMPLEMENTEDThe count isunique_pointsfrom 7.1.4.2.3.: how many different files point at the node. A node is below the cutoff whenunique_pointsis less than the setting. A node at the cutoff is drawn.- acceptance: The setting is 5. A node with
unique_points4 is absent from the opening draw. A node withunique_points5 is drawn.
- acceptance: The setting is 5. A node with
- 7.1.4.16.2.
NOT_IMPLEMENTED0disables the filter. A missing key, or a value that is not an integer of 0 or more, is the same as0. Every node is drawn, still subject to the Show Orphans, Show External Links, and Show Sources toggles.- acceptance: With the key absent or set to
0, a node withunique_points0 is drawn when those toggles allow it.
- acceptance: With the key absent or set to
- 7.1.4.16.3.
NOT_IMPLEMENTEDA parent of a node is any node with an edge whose target is that node. While a parent is the clicked node, each direct target is drawn even when it is below the cutoff. The clicked node stays drawn for as long as it stays clicked, including when it is below the cutoff. Clearing the click hides a below-cutoff node again. Clicking a node draws its direct targets only, not the targets of those targets.- acceptance: The setting is 5. Page A has
unique_points5 and links to B. B hasunique_points1 and links to C. C hasunique_points1. The opening draw shows A and hides B and C. Clicking A draws B and leaves C hidden. Clicking B keeps B drawn and draws C. Clicking empty space hides B and C. A node with no incoming edge stays hidden, because it has no parent to click.
- acceptance: The setting is 5. Page A has
- 7.1.4.16.4.
NOT_IMPLEMENTEDAn edge is drawn only when both of its nodes are drawn. See all, the opening fit, and search use that same drawn set. A hidden node is left out of the fit, as 7.1.4.7. does for a hidden orphan, and it is not a search match.- acceptance: An edge into a below-cutoff node is absent until a click draws that node. Searching for its name does not draw it.
- 7.1.4.16.5.
NOT_IMPLEMENTEDShow Orphans, Show External Links, and Show Sources still apply. A node hidden by one of those toggles stays hidden when it meets the cutoff or when its parent is clicked.- acceptance: With Show External Links unchecked, clicking a page does not draw the external node it links to.
- 7.1.4.16.6.
NOT_IMPLEMENTED--format jsonand--jsonstill list every node and edge. The filter changes the HTML draw only.- acceptance: JSON includes a node whose
unique_pointsis below the setting.
- acceptance: JSON includes a node whose
- 7.1.4.16.1.
- 7.1.4.20.
fiona.wiki.graph.ignore_filesis a list of glob patterns in the wiki'sfiona-settings.json. A markdown file whose path relative to the scan root matches is not a graph node. HTML and JSON both omit it. An edge that would start or end at that file is omitted. The file does not count towardmax_filesand is not an orphan. A missing key is an empty list. A value that is not a list of strings raisesValueErrorwith the textfiona.wiki.graph.ignore_files must be a list of strings. A pattern that starts with*/also matches that same path at the scan root. The shipped list is*/table_of_contents.md,*/README.md, and*/AGENTS.md. A table of contents links to every page, so leaving it in the graph hides the real links. A README or AGENTS file describes the tree, not the wiki's knowledge, so it is left out too.- acceptance: With that pattern,
table_of_contents.mdat the scan root anddocs/table_of_contents.mdare absent from JSONnodes,edges, andorphans.a.mdandb.mdstay. An edge from the table of contents toa.mdis absent. An edge froma.mdto the table of contents is absent. - acceptance:
max_filesis 1. The directory holdstable_of_contents.mdandkept.md. JSONfile_countis 1 and the only node iskept.md. - acceptance: A non-list
ignore_filesmakeswiki graphraiseValueErrorwith that text.
- acceptance: With that pattern,
- 7.1.4.17.
NOT_IMPLEMENTEDA markdown file that.gitignorematches is not a graph node. HTML and JSON both omit it. An edge that would start or end at that file is omitted. The file does not count towardmax_files. Housekeeping's orphan list (7.2.6.) uses this graph, so an omitted file is not an orphan. There is no setting that turns this off.- acceptance: The scanned
.gitignorelistssecret.md.secret.mdis absent from JSONnodes,edges, andorphans. A page that links to it has no edge to it. - acceptance:
max_filesis 1. The directory holdskept.mdand a gitignoredsecret.md. JSONfile_countis 1 and the only node iskept.md. - 7.1.4.17.1.
NOT_IMPLEMENTEDPatterns are the non-comment, non-blank lines of the.gitignorein the scanned directory, and of each.gitignorein a subdirectory. A subdirectory file's patterns match only paths under that subdirectory. Matching is 7.1.2.10.: a pattern with no slash matches any path segment, and a pattern that ends with/matches that directory and everything under it.- acceptance: The scanned
.gitignorelistsdrafts/.drafts/note.mdis absent.wiki/note.mdis present. - acceptance: A line
# secret.mddoes not omitsecret.md. - acceptance:
notes/.gitignorelistsscratch.md.notes/scratch.mdis absent.scratch.mdat the scan root stays.
- acceptance: The scanned
- 7.1.4.17.2.
NOT_IMPLEMENTEDA path under.git/is omitted even when no pattern names it.- acceptance: With no
.gitignore, a markdown file under the scan root stays, and a markdown file under.git/is absent.
- acceptance: With no
- acceptance: The scanned
- 7.1.4.18.
NOT_IMPLEMENTEDThe HTML graph draws a crowded directory as one directory node. That keeps a large wiki readable and cuts the number of shapes the page simulates. The settings aredirectory_nodes.min_filesanddirectory_nodes.outside_depthin section 5.1.- 7.1.4.18.1.
NOT_IMPLEMENTEDA directory collapses when it holds at leastmin_filesmarkdown pages directly. Pages in its subdirectories do not count toward that number. The scan root never collapses.0, a missing key, or a value that is not an integer of 0 or more turns collapsing off, and the graph is drawn as it is today.- acceptance:
min_filesis 3.wiki/concepts/holdsa.md,b.md, andc.md. The opening draw has one nodewiki/concepts/and no node for those three pages. - acceptance:
min_filesis 3.wiki/notes/holds two pages directly andwiki/notes/deep/holds three. The opening draw shows both pages ofwiki/notes/and one nodewiki/notes/deep/. - acceptance: With the key absent or
0, no directory node is drawn.
- acceptance:
- 7.1.4.18.2.
NOT_IMPLEMENTEDA directory node stands for every page under that directory, including its subdirectories. Its id is the directory path relative to the scan root with a trailing/. Its name and subtitle are the last path segment with a trailing/. A collapsed directory inside another collapsed directory is drawn only in its parent's view (7.1.4.18.4.).- acceptance: The node for
wiki/concepts/has idwiki/concepts/and subtitleconcepts/.
- acceptance: The node for
- 7.1.4.18.3.
NOT_IMPLEMENTEDA directory node acts like a page node. The edges of its pages are drawn on it.- 7.1.4.18.3.1.
NOT_IMPLEMENTEDAn edge between a page inside and a node outside is redrawn between the directory node and that outside node. Edges that land on the same pair merge into one edge whose weight is the sum. An edge with both ends inside the directory is not drawn in the view that shows the directory node.- acceptance:
wiki/index.mdlinks once toa.mdand twice tob.md, both inside collapsedwiki/concepts/. One edge runs fromwiki/index.mdtowiki/concepts/with weight 3. A link froma.mdtob.mddraws no edge in that view.
- acceptance:
- 7.1.4.18.3.2.
NOT_IMPLEMENTEDunique_points,total_points,link_score, in-degree, and out-degree are computed from those merged edges with the rule in 7.1.4.2.3.. Size and color followlink_scorelike any node.- acceptance: In the example above, the directory node
has
unique_points1,total_points3, and in-degree 1.
- acceptance: In the example above, the directory node
has
- 7.1.4.18.3.3.
NOT_IMPLEMENTEDHover, click highlight, drag, glow, the hover card, and the toggles behave as for a page. The click card showspath,pages(every page under the directory), then unique points, total points, in-degree, and out-degree. It has no frontmatter fields. - 7.1.4.18.3.4.
NOT_IMPLEMENTEDSearch matches a directory node when its name matches, or when the name of a page under it matches. External links andsourcenodes of its pages hang from the directory node.- acceptance: Searching
a.mdwhilewiki/concepts/is collapsed highlights thewiki/concepts/node.
- acceptance: Searching
- 7.1.4.18.3.5.
NOT_IMPLEMENTEDThe shape isshapes.directoryfrom the active theme (section 5.3). The Legend's shape group adds a directory entry while a directory node is drawn.- acceptance: A theme that sets
shapes.directorytostardraws the directory node as a star. A theme that omits the key usesfolderfromcolorful.
- acceptance: A theme that sets
- 7.1.4.18.3.1.
- 7.1.4.18.4.
NOT_IMPLEMENTEDDouble click on a directory node opens that directory's view. The other nodes leave the page. The view draws the pages that sit directly in the directory, one directory node for each collapsed subdirectory, the pages of each subdirectory that does not collapse, and the edges between them. A collapsed subdirectory follows 7.1.4.18.1. inside the view. The view runs the See all fit from 7.1.4.7..- acceptance: Double click on
wiki/concepts/drawsa.md,b.md, andc.md, the edge froma.mdtob.md, and no node that sits outsidewiki/concepts/except the ones in 7.1.4.18.5..
- acceptance: Double click on
- 7.1.4.18.5.
NOT_IMPLEMENTEDA node outside the directory is drawn in its view when a page inside points at it, withinoutside_depthhops along the direction of the edges. Depth1draws the direct targets. Depth2also draws their targets. Depth0draws no outside node. An outside node is drawn the way the opening draw shows it: as its page, or as the collapsed directory that holds it. Outside nodes and their edges are drawn at half opacity. A node that only points into the directory is not drawn.- acceptance:
outside_depthis 1.a.mdlinks towiki/index.md, andwiki/index.mdlinks towiki/log.md. Thewiki/concepts/view drawswiki/index.mdat half opacity and does not drawwiki/log.md. With depth 2 it draws both. - acceptance:
outside_depthis 1 anda.mdlinks towiki/other/x.md, inside collapsedwiki/other/. The view draws the nodewiki/other/and no nodewiki/other/x.md.
- acceptance:
- 7.1.4.18.6.
NOT_IMPLEMENTEDA bar at the upper center of the graph names the open view as a path, for exampleAll / wiki / concepts. Each segment opens that view. A button labeled "Back" opens the parent view and is disabled on the opening view. The open view is kept in the page hash as#dir=<id>, so browser back and forward move between views and a reload reopens the same view. A hash that names no collapsed directory opens the opening view.- acceptance: From
wiki/concepts/, Back draws the opening view again with thewiki/concepts/node.
- acceptance: From
- 7.1.4.18.7.
NOT_IMPLEMENTEDShow Orphans, Show External Links, Show Sources, search, See all, andnode_importance_min_point(7.1.4.16.) apply to the nodes of the open view only. A double click on an outside page in a view opens that file. A double click on an outside directory node opens that directory's view. - 7.1.4.18.8.
NOT_IMPLEMENTED--format jsonand--jsonlist every page and edge, as today. Collapsing changes the HTML draw only.- acceptance: JSON with
min_files3 still listsa.md,b.md, andc.mdas nodes.
- acceptance: JSON with
- 7.1.4.18.1.
- 7.1.4.19.
NOT_IMPLEMENTEDwiki graph --serveis a light live view. It builds the graph, serves it over local HTTP, and rebuilds when a scanned file changes. The open page then shows the change without a manual refresh. It uses the standard library only and adds no dependency.- 7.1.4.19.1.
NOT_IMPLEMENTEDThe server binds--host(defaultserve.host,127.0.0.1) and--port(defaultserve.port, 8765). Port0picks a free port. On start it printsServing wiki graph at http://<host>:<port>/ (Ctrl+C to stop)on stdout and opens that URL in the default browser, unless--no-openis set. Ctrl+C stops it, printsStopped, and exits 0. A host other than127.0.0.1,localhost, or::1prints a warning on stderr that the wiki is readable from the network.- acceptance:
--serve --port 0 --no-openprints the URL with a port above 0, and opens no browser. - acceptance: A port already in use prints an error on stderr and exits 1.
- acceptance:
- 7.1.4.19.2.
NOT_IMPLEMENTED--servewith--format jsonor--jsonis a usage error with exit 2.--host,--port, or--no-openwithout--serveis the same usage error.--servewrites no file unless-ois given. Then the server writes that file after every build. - 7.1.4.19.3.
NOT_IMPLEMENTEDThe server answersGETonly. Another method is 405.- 7.1.4.19.3.1.
NOT_IMPLEMENTED/is the current graph HTML: the same page as 7.1.4.5., plus the live script in 7.1.4.19.5.. - 7.1.4.19.3.2.
NOT_IMPLEMENTED/graph.jsonis the current JSON from 7.1.4.3. withmetadata.buildadded.buildstarts at 1 and adds 1 on every rebuild. - 7.1.4.19.3.3.
NOT_IMPLEMENTED/eventsis a Server-Sent Events stream. After each rebuild it sendsevent: graphwithdata: {"build": <n>}. A comment line goes out every 15 seconds so the connection stays open. - 7.1.4.19.3.4.
NOT_IMPLEMENTED/files/<path>returns a markdown file under the scan root astext/plain; charset=utf-8. A path that leaves the scan root, a path that is not a scanned file, or a missing file is 404. In a served page, a double click on a page opens this URL in place offile://.- acceptance:
/files/../secret.mdand/files/%2e%2e/secret.mdare 404.
- acceptance:
- 7.1.4.19.3.5.
NOT_IMPLEMENTEDAny other path is 404.
- 7.1.4.19.3.1.
- 7.1.4.19.4.
NOT_IMPLEMENTEDThe watcher polls everyserve.poll_secondsseconds. It compares the set of matched markdown files and each file's modification time and size. The match is the include and exclude patterns and the.gitignorerule in 7.1.4.17.. The nearestfiona-settings.jsonand theconstellation/files from section 5.3 are watched too. A change waitsserve.debounce_mswith no newer change, then one rebuild runs. Several saves in that window cause one rebuild.- acceptance: Adding
new.mdthat links toa.mdmakes the next/graph.jsonlist nodenew.mdand an edge toa.md, and/eventssends onegraphevent. - acceptance: Deleting a page removes its node and its
edges from the next
/graph.json. - acceptance: Saving three files within the debounce window
raises
buildby 1.
- acceptance: Adding
- 7.1.4.19.5.
NOT_IMPLEMENTEDThe served page listens on/events. On agraphevent whosebuildis newer than its own, it saves its state tosessionStorage, then reloads. The state is the zoom transform, each drawn node's position by id, the clicked node, the open directory view, every toggle, the theme, and the search text. After the reload the page restores that state once, places known nodes where they were, and fades in only the new nodes. The restore replaces the reset in 7.1.4.5.18. for that one load. A manual refresh still resets the controls.- acceptance: After a rebuild adds
new.md, an existing node keeps its position within 1em, the theme and toggles are unchanged, andnew.mdfades in.
- acceptance: After a rebuild adds
- 7.1.4.19.6.
NOT_IMPLEMENTEDA rebuild that fails keeps the last good graph. The error prints on stderr and the server keeps running. Nographevent is sent. - 7.1.4.19.7.
NOT_IMPLEMENTEDA file written without--servecontains no live script and opens no connection.- acceptance: Plain
wiki graphoutput does not containEventSource.
- acceptance: Plain
- 7.1.4.19.8.
NOT_IMPLEMENTEDThe server makes no outbound call. It reads only files under the scan root and the settings and theme files of section 5.
- 7.1.4.19.1.
7.1.5. wiki ingest
Status: Partially Implemented
Implements section 4.7.6. An ingest has two phases. The tool runs
the first: it turns one source into a file on disk, archives a copy
under raw/, converts that copy to markdown, and writes a wiki page
with status: raw. The agent runs the second: it refines the page
and sets status: refined. The Fiona skill teaches the second
phase and when to convert a source by hand. The pattern both phases
follow is section 3.1 of
llm-wiki-mod.
The tool runs five stages in order. Each stage has one base class and one job. Class names are in Appendix D.
| Stage | Input | Output |
|---|---|---|
| Fetch | the <source> argument |
a local file, its origin, and its media type |
| Archive | that local file | a file under raw/ |
| Convert | the archived file | markdown body, title, metadata, conversion state, warnings |
| Write | the conversion | one page under wiki/ with status: raw (under refine/ once 7.1.5.15. is built) |
| Record | the run | one line appended to wiki/log.md |
Shipped converters, in registration order:
| Converter | Media types | Extensions | Raw category | Library |
|---|---|---|---|---|
markdown |
text/markdown |
.md, .markdown |
articles |
none |
text |
text/plain |
.txt, .text, .log |
articles |
none |
html |
text/html, application/xhtml+xml |
.html, .htm, .xhtml |
articles |
beautifulsoup4, markdownify |
pdf |
application/pdf |
.pdf |
papers |
pypdf |
A source that no converter claims is archived under raw/other/.
Pure-Python libraries are preferred so the install stays light.
Candidates for later formats are in Appendix C.
- 7.1.5.1. The pipeline is built from parts.
- 7.1.5.1.1. The pipeline receives its fetchers, converter registry, archiver, page writer, and log writer as constructor arguments. It holds no format-specific code.
- 7.1.5.1.2. A converter declares its name, media types,
extensions, and raw category as class attributes, and implements
one
convertmethod. Adding a format is one new converter class, one registration, and its tests.- acceptance: A test registers a converter for
application/x-testand ingests a.xtestfile into a page. No pipeline, archiver, or writer module changes.
- acceptance: A test registers a converter for
- 7.1.5.1.3. A fetcher declares whether it accepts an argument and
returns the fetched source. The URL fetcher takes its opener as
an argument.
- acceptance: Tests run the URL path with a fake opener and make no network call.
- 7.1.5.2. Fetch.
- 7.1.5.2.1. An argument that starts with
http://orhttps://is a URL. Any other<scheme>://prefix exits 1 withError: Unsupported URL scheme: <scheme>. Anything else is a local path. A missing path and a directory each exit 1 with the message from section 4.7.6.- acceptance:
ftp://host/a.pdfexits 1 and writes nothing.
- acceptance:
- 7.1.5.2.2. A URL is downloaded with
urllib.requestintoingest/<slug>.<ext>. Redirects are followed. Proxies come from the environment. The request sendsuser_agentand waits up totimeout_seconds. No credentials are sent. - 7.1.5.2.3. A non-2xx response or a network error exits 1 with
Error: Download failed: <url>: <reason>. A response that needs a login is 7.1.5.2.8. instead. The reason names the HTTP status when there is one. A body larger thanmax_download_bytesstops the download and exits 1. In each case the partial file is deleted andingest/is unchanged.- acceptance: A fake opener that answers 404 exits 1, the
message contains
404, andingest/has the same files as before.
- acceptance: A fake opener that answers 404 exits 1, the
message contains
- 7.1.5.2.4. The media type is the response
Content-Typewithout parameters. Acharsetparameter is kept as a decoding hint. With no usable header, the extension decides, using the converter table and thenmimetypes. With no known extension, the first 1024 bytes decide:%PDF-isapplication/pdf,<!doctype htmlor<htmlin any case istext/html, valid UTF-8 with no NUL byte istext/plain. Anything else isapplication/octet-stream.- acceptance: A local file named
noteswhose bytes start with%PDF-is converted bypdf.
- acceptance: A local file named
- 7.1.5.2.5. A downloaded file takes the first extension of the
converter that claims its media type, then the URL path suffix,
then
.bin.- acceptance:
https://host/reportserved asapplication/pdfis saved asingest/report.pdf.
- acceptance:
- 7.1.5.2.6. The slug of a URL is built from its last three
non-empty path segments, each without its extension, with a
segment named
indexdropped. An empty path uses the host. The slug of a file is its stem. The text is lowercased, each run of characters outside[a-z0-9]becomes one-, leading and trailing-are trimmed, and the result is cut to 80 characters. An empty result issource.- acceptance:
https://host/job/performance_TL153/2108/consolehas the slugperformance-tl153-2108-console.
- acceptance:
- 7.1.5.2.7.
NOT_IMPLEMENTEDA local path is resolved against the current directory../,.\, and either separator are accepted on Windows. A missing path inside the wiki'singest/is often a file an earlier run already moved (7.1.5.3.6.). When a file with the same name exists underraw/, the error adds one space and(moved to <raw path> by an earlier ingest). Several matches use the first in sorted path order.- acceptance: Ingesting
./ingest/a.mdand then.\ingest\a.mdexits 0, then exits 1 withError: Source not found: .\ingest\a.md (moved to raw/articles/a.md by an earlier ingest)on one line.
- acceptance: Ingesting
- 7.1.5.2.8. A URL that needs a login is an
error, not a source. The tool cannot log in, so it stops and
leaves the next step to the agent (7.1.5.14.). A login page
must never reach
raw/as if it were the source.-
7.1.5.2.8.1. The tool sends no credentials, cookies, or tokens, and reads none from the environment or from a file (7.1.5.2.2.). It never asks for a password.
-
7.1.5.2.8.2. Three checks run in this order. The first hit decides the reason:
Check Hit when Reason text Status The response is HTTP 401 or 403 <status> <phrase>, e.g.401 UnauthorizedRedirect The final URL differs from the requested URL and its host and path match one of login_url_patternsredirected to <final url>Login form The media type is text/htmland the body has an<input>whosetypeispassword, in any case or quotinglogin page at <final url> -
7.1.5.2.8.3.
login_url_patternsis a list of regular expressions, searched case-insensitively in<host><path>of the final URL. The query string is not searched. The default list is in section 5.1. The redirect check is skipped when there was no redirect, so a user can still ingest a page whose own path holdslogin. -
7.1.5.2.8.4. On a hit, stderr has the
Error: Authentication requiredline and theNext:line from section 4.7.6, and the command exits 4. The body is read withinmax_download_bytesand then dropped. Nothing is written underingest/,raw/, orwiki/, andwiki/log.mdis unchanged. The URL in both lines is the one the user passed, with userinfo removed. -
7.1.5.2.8.5.
--dry-runruns the same checks and exits 4 the same way.--jsonprints nothing on stdout (7.1.5.13.). -
7.1.5.2.8.6. An HTML page that passes the three checks but has no text still converts as
partialwith the warning in 7.1.5.4.5.5.. Login detection does not replace that warning. -
acceptance: A fake opener that answers 401 exits 4. Stderr has
Authentication required,401, and theNext:line.ingest/,raw/,wiki/, andwiki/log.mdhave the same hashes as before. -
acceptance: A fake opener that redirects
https://host/job/x/consoletohttps://host/login?from=%2Fjob%2Fx%2Fconsoleand answers 200 exits 4 with the reasonredirected to https://host/login?.... -
acceptance: A fake opener that answers 200 with an HTML form holding
<INPUT TYPE='password'>exits 4 with the reasonlogin page at <url>. -
acceptance: A 200 HTML page at
https://host/docs/login, with no redirect and no password input, is ingested with exit 0. -
acceptance: A 404 still exits 1 with
Download failed.
-
- 7.1.5.2.9.
--origin URLrecords where a local file came from, so a source saved by hand after 7.1.5.2.8. keeps its real provenance.- 7.1.5.2.9.1.
--originis valid only when<source>is a local path. With a URL source it exits 1 withError: --origin needs a local file: <source>. A value that is nothttp://orhttps://exits 1 withError: --origin must be an http or https URL: <value>. Both checks run before fetch. - 7.1.5.2.9.2. The file is fetched, archived, and moved as any
local file. The page frontmatter then has
ingest.originset to the URL without userinfo,origin_kind: url, andfinal_url: null. Thehtmlconverter uses that URL to make relative links absolute (7.1.5.4.5.3.). The log bullet names that URL (7.1.5.6.). JSONoriginandorigin_kindmatch the frontmatter. - 7.1.5.2.9.3. The slug and default raw name still come from
the file stem (7.1.5.2.6.), so the name the agent chose in
ingest/is kept. - acceptance:
wiki ingest ingest/console.html --origin https://host/job/x/consoleexits 0. The page hasorigin: https://host/job/x/console,origin_kind: url, and a relative link/ain the file becomeshttps://host/a. No network call is made. - acceptance:
wiki ingest https://host/a --origin https://host/bexits 1 and makes no network call.
- 7.1.5.2.9.1.
- 7.1.5.2.10. A local file inside the wiki root is recorded by
its path relative to the wiki root, with
/separators, e.g.ingest/notes.txt. The wiki can be cloned anywhere, so an absolute path inside it is wrong on every other machine. A file outside the wiki root keeps its resolved absolute path. Thisoriginis the same in the page frontmatter, the JSON result, and the log bullet (7.1.5.6.).--originreplaces it (7.1.5.2.9.2.).- acceptance:
wiki ingest <wiki>/ingest/a.txt, given as an absolute path, writesorigin: ingest/a.txtandorigin_kind: file, and the log bullet namesingest/a.txt. A file under the system temp directory, outside the wiki, keeps its absolute path.
- acceptance:
- 7.1.5.2.1. An argument that starts with
- 7.1.5.3. Archive.
- 7.1.5.3.1. The default raw path is
raw/<category>/<slug>.<ext>. The category is the raw category of the converter that claims the media type, unlessraw_categoriesmaps that converter name to another directory. With no converter it isother.- acceptance: A PDF is archived at
raw/papers/<slug>.pdf.
- acceptance: A PDF is archived at
- 7.1.5.3.2.
-r/--raw PATHis relative toraw/. A leadingraw/is accepted. A value that ends in an extension names the file. Any other value is a directory, and the file inside it is<slug>.<ext>. Missing directories are created. After resolving..and symlinks the path must be insideraw/, else exit 1 with nothing written.- acceptance:
-r jenkins/tl153archives an HTML source atraw/jenkins/tl153/<slug>.html.-r ../wiki/xexits 1.
- acceptance:
- 7.1.5.3.3. Before writing, the archive computes the SHA-256 of
the fetched file and compares it with every file under
raw/. Only files of the same byte size are hashed. A match anywhere underraw/, at any name or directory, is reused: nothing is written underraw/,raw_pathis the matching file, andraw_reusedis true. When-rnames another place, the match still wins and adds the warningalready archived at <raw path>; --raw ignored. Several matches use the first in sorted path order.- acceptance: Ingesting one file twice, the second time under
another name and with
-r other/dir, leaves one raw copy and the second run reportsraw_reused: trueand that copy's path. - acceptance: A URL whose body matches an archived file reuses that file.
- acceptance: Ingesting one file twice, the second time under
another name and with
- 7.1.5.3.4. The archive never overwrites, renames, or deletes a
file under
raw/. When the raw path holds a file with different bytes, the first free name of<slug>-2.<ext>,<slug>-3.<ext>, and so on is used.- acceptance: Ingesting a changed file of the same name creates
<slug>-2.<ext>and the first copy is unchanged.
- acceptance: Ingesting a changed file of the same name creates
- 7.1.5.3.5. When the raw copy is reused and a page under
wiki/already has that raw path insourcesor that hash iningest.sha256, the run is a duplicate. It prints theDuplicate:line, setsduplicate_page, writes no page and no log line, and exits 0.--forceconverts again and replaces that page, at its current path unless-tis set.- acceptance: A second ingest of the same bytes exits 0,
reports the first page as
duplicate_page, and leaves every file under the wiki unchanged apart from the moved source.
- acceptance: A second ingest of the same bytes exits 0,
reports the first page as
- 7.1.5.3.6. A file inside the wiki's
ingest/directory is moved intoraw/, so it leaves the drop zone. A downloaded file is iningest/, so it is moved too. When the raw copy is reused, theingest/file is deleted, becauseraw/already holds its bytes. Any other file is copied and the original is left as it was. A file already underraw/is not archived again, and conversion reads it in place.-ron such a file exits 1.- acceptance: After ingesting
ingest/a.pdf, that path is gone andraw/papers/a.pdfholds its bytes. A file ingested frompersonal/is copied and the original is unchanged.
- acceptance: After ingesting
- 7.1.5.3.1. The default raw path is
- 7.1.5.4. Convert.
- 7.1.5.4.1. The registry picks the first converter, in
registration order, whose media types contain the detected type,
then the first whose extensions contain the file extension. With
no match, no page is written, stdout ends with the
No converterline, and the command exits 3.- acceptance: A
.xyzfile of random bytes exits 3 and is archived underraw/other/.
- acceptance: A
- 7.1.5.4.2. A converter returns the markdown body, a title or
none, a metadata map, a conversion state of
completeorpartial, and a list of warnings. A converter that cannot read a file it claims, such as a corrupt or encrypted PDF, raises a conversion error. The command then writes no page, printsError: Conversion failed: <converter>: <reason>on stderr, and exits 3. The raw copy stays.- acceptance: An encrypted PDF exits 3, its raw copy exists, and no page is written.
- 7.1.5.4.3.
markdownkeeps the body byte for byte. A frontmatter block in the source moves intosource_meta. The title is that frontmattertitle, then the first H1, then the slug. - 7.1.5.4.4.
textdecodes UTF-8 with any BOM stripped, then the charset hint, thencp1252. A fallback decode adds a warning. The body is one fencedtextblock whose fence is longer than any backtick run in the text. The title is the slug. - 7.1.5.4.5.
htmlparses with beautifulsoup4 and converts with markdownify.- 7.1.5.4.5.1. The title is
<title>, thenog:title, then the first<h1>in<body>that has text.source_metaholdslang, the canonical link, and thedescription,author,og:*, andarticle:published_timemeta values that are present. - 7.1.5.4.5.2.
script,style,noscript,template, and comments are dropped. The content is<body>, read by the block sweep in 7.1.5.4.5.6. Atemplatethat has ashadowrootmodeattribute is kept (7.1.5.4.5.6.1.). - 7.1.5.4.5.3. A relative
hreforsrcis made absolute against<base href>, then the origin URL. A local file has no origin URL, so its relative links are left to 7.1.5.5.4.. - 7.1.5.4.5.4. Headings are ATX. Bullets use
-.<pre>becomes a fenced block. A table becomes a pipe table. - 7.1.5.4.5.5. A body with no text outside markup is
partialwith the warningno text content; the page may need JavaScript or a login. - 7.1.5.4.5.6. Block sweep. The first
<article>is often a card, not the page. A landing page can hold its text in plain<div>and<section>elements and use<article>only for testimonials. So the converter reads every block of<body>, scores each one with fixed rules, and writes it askeep,review, ordrop. The script decides what is worth taking. The agent decides about thereviewblocks when it refines the page. The rules name no site. They read only HTML structure, so the same rules serve a landing page, an encyclopedia article, a Q&A page, and a forum thread.- 7.1.5.4.5.6.1. The sweep walks
<body>in document order, after the drops in 7.1.5.4.5.2. Atemplatewith ashadowrootmodeattribute is a declarative shadow root. It is not dropped, and the sweep reads its content in place. A block is the outermosth1toh6,p,ul,ol,dl,blockquote,pre,table, orfigure. Atablewhose cells hold anothertable, adiv, or any block element is a layout table. It is not a block, and the sweep reads its cells as containers. - 7.1.5.4.5.6.1.1. An inline element is
a,abbr,b,bdi,br,cite,code,data,del,dfn,em,font,i,img,ins,kbd,label,mark,q,s,samp,small,span,strong,sub,sup,time,u,var, orwbr. Every other element is a container. That includes a custom element, whose name holds a hyphen, such as<my-comment>. - 7.1.5.4.5.6.1.2. A run of text nodes and inline elements
that sits directly in a container is one loose-text block.
So
<div><span>Fast</span> evals</div>is one block with the textFast evals, and so is<my-post>Fast evals</my-post>. - 7.1.5.4.5.6.2. The text of a block is its text with
whitespace runs folded to one space and trimmed. The link
text is the part of that text inside
<a>. The word count splits the text on spaces. - 7.1.5.4.5.6.3. A block is
dropwhen any of these holds:- its text has no letter or digit;
- it has fewer words than
fiona.wiki.ingest.html.min_wordsand its case-folded text equals that of an earlierkeeporreviewblock, such as a repeatedShareorReply; - it sits inside
nav,button,select, an element with thehiddenattribute, an element witharia-hidden="true", or an element whosestyleattribute setsdisplay: noneorvisibility: hidden.
- 7.1.5.4.5.6.4. A block that is not
dropisreview, with the first reason that holds, in this order:chrome: it sits insideaside,form,dialog, an element whoseroleisnavigation,banner,contentinfo, orcomplementary, or aheaderorfooterthat is not inside<article>or<main>.repeat: its case-folded text equals that of an earlierkeeporreviewblock. A long repeat can be a quote in a reply or the same code in two answers, so the agent decides.links: link text over text length is greater thanfiona.wiki.ingest.html.max_link_density.short: apor loose-text block has fewer words thanfiona.wiki.ingest.html.min_words. Headings, lists,pre, and tables are nevershort.
- 7.1.5.4.5.6.5. Every other block is
keep. - 7.1.5.4.5.6.6. The body is each
keepandreviewblock in document order, each converted with the options of 7.1.5.4.5.4., separated by one blank line. Areviewblock sits between the line<!-- fiona:review <reason> -->and the line<!-- /fiona:review -->. Adropblock is not written. - 7.1.5.4.5.6.7. The warnings gain one entry,
html sweep: <k> keep, <r> review, <d> drop. When no block iskeepand at least one isreview, the result ispartialwith the warningno block passed the content checks; every block is marked for review. - 7.1.5.4.5.6.8. The same bytes and settings give the same body. The sweep reads no clock, network, or random source.
- 7.1.5.4.5.6.9. When the agent refines the page, it keeps
each
reviewblock by removing its two marker lines, or deletes the block with its markers. A refined page holds nofiona:reviewmarker. - 7.1.5.4.5.6.10. The sweep reads only the HTML it is given.
Text that JavaScript builds after load, comments behind a
load morecontrol, and pages behind a login, consent wall, or bot check are not in that HTML. Those cases are 7.1.5.4.5.5., 7.1.5.2.8., and 7.1.5.14., not the sweep. - acceptance: A fixture with no
<main>, a<section>holding<h2>How it works</h2>and a<div>of twelve words, and then two<article>testimonial cards, gives a body holding the heading, the twelve words, and both card quotes, in that order. - acceptance: In a fixture with a nav list, a footer
paragraph, a
<span>•</span>, a<span>Share</span>twice, a twelve-word paragraph twice, a list whose text is all links, and a two-word<div>, the nav text and the bullet are absent,Shareappears once, and the footer paragraph, the second copy of the paragraph, the link list, and the two-word text sit insidefiona:reviewmarkers with the reasonschrome,repeat,links, andshort. - acceptance: An encyclopedia-style fixture with a side
menu in
nav, an infobox table, body paragraphs with<sup>citation links, a reference list, and a navbox table of links keeps every body paragraph outside review markers. The reference list and the navbox arelinks, and no menu text is in the body. - acceptance: A Q&A-style fixture with a question, two
answers that hold
preblocks, the sameprein both answers, the vote counts<div>42</div>,<div>7</div>, and<div>3</div>on the three posts, and a related-questionsasidekeeps the question and both answers in order. The secondpreisrepeat, each vote count isshort, and the aside ischrome. - acceptance: A forum-style fixture whose posts are custom
elements, one post inside a
<template shadowrootmode="open">, nested replies, and a hiddenstyle="display: none"reply keeps the text of every visible post and reply in document order, holds the shadow-root post, and has no text of the hidden reply. - acceptance: A layout table whose cells hold
divposts gives one block per post, not a pipe table. - acceptance: Two conversions of the same fixture give
byte-identical bodies, and the warnings hold the
html sweep:entry with the counts of that fixture. - acceptance: Fiona skill section 18 has the step in 7.1.5.4.5.6.9.
- 7.1.5.4.5.6.1. The sweep walks
- acceptance: For a fixture with a nav, an article, a script,
a relative link
/a, and a table, fetched fromhttps://host/p, the body holds the article text, no script text, the linkhttps://host/a, and a pipe table.
- 7.1.5.4.5.1. The title is
- 7.1.5.4.6.
pdfreads with pypdf.- 7.1.5.4.6.1.
source_metaholds the page count and the/Title,/Author,/Subject,/Keywords,/CreationDate, and/ModDatevalues that are present. Dates are ISO 8601. The title is the metadata title, then the slug. - 7.1.5.4.6.2. With an outline, each outline entry becomes a
heading before the text of its destination page. The level is
the entry depth plus 2, capped at 6. Without one, each page
starts with
## Page <n>. - 7.1.5.4.6.3. A page with no text adds the warning
page <n> has no text layerand makes the resultpartial. When every page is empty, the one warning isno text layer; the PDF may be scanned. - acceptance: A two-page fixture with no outline has
## Page 1and## Page 2. A fixture with one blank page ispartialand names that page.
- 7.1.5.4.6.1.
- 7.1.5.4.1. The registry picks the first converter, in
registration order, whose media types contain the detected type,
then the first whose extensions contain the file extension. With
no match, no page is written, stdout ends with the
- 7.1.5.5. Write.
-
7.1.5.5.1. The default page is
wiki/<default_target>/<slug>.md.-t/--target PATHis relative towiki/, and a leadingwiki/is accepted. A value that ends in.mdnames the page. Any other value is a directory, and the page inside it is<slug>.md. After resolving..and symlinks the path must be insidewiki/, and it must not bewiki/index.md,wiki/log.md,wiki/schema.md, or a file underwiki/logs/. Else exit 1.NOT_IMPLEMENTEDThe page is then staged atrefine/plus the same relative path (7.1.5.15.1.).- acceptance:
-t conceptswriteswiki/concepts/<slug>.md.-t ../raw/x.mdand-t index.mdexit 1.
- acceptance:
-
7.1.5.5.2. An existing page exits 1 unless
--forceis set. The check runs before fetch, so a refusal writes nothing and downloads nothing.- acceptance: A second run on the same source exits 1 and the
page bytes are unchanged. With
--forcethe page is replaced.
- acceptance: A second run on the same source exits 1 and the
page bytes are unchanged. With
-
7.1.5.5.3. The page frontmatter is complete when the run ends. Every key below is present, in this order, even when its value is empty:
[],{}, ornull.sourcesis the raw path relative to the wiki root.titleis the converter title, else the slug.ingestis filled from the fetch, archive, and convert stages, so its values are facts about this run.--- name: <slug> version: 0.1.0 title: <title> created: <YYYY-MM-DD> updated: <YYYY-MM-DD> type: summary status: raw sources: [<raw path>] source_meta: {<key>: <value>} ingest: origin: <url, or file path (*7.1.5.2.10.*)> origin_kind: <url or file> final_url: <url after redirects, or null> fetched: <UTC time, YYYY-MM-DDTHH:MM:SSZ> media_type: <media type> size_bytes: <int> sha256: <64 lowercase hex of the raw copy> raw_reused: <true or false> converter: <converter name> conversion: <complete or partial> warnings: [<text>] tool: fiona-assistant <package version> tags: [] confidence: zero llm: - model: none contested: false contradictions: [] ---- acceptance: For each fixture, the page frontmatter parses
and has every key above.
ingest.sha256equals the SHA-256 of the file atsources[0], andingest.warningsequals the JSONwarnings.
- acceptance: For each fixture, the page frontmatter parses
and has every key above.
-
7.1.5.5.4. The body is
# <title>, a blank line, the lineRaw ingest of [<raw file name>](<link to the raw file>). Not refined yet., a blank line, and the converted body. When the converted body has an H1, every heading in it moves down one level, and H6 stays H6. A relative link or image that does not resolve from the page is replaced by its text, and the count is one warning.- acceptance: The page has exactly one H1, and mdlinter reports no MDL001 for it.
-
7.1.5.5.5. After writing, the writer runs the pymarkdown fixer on that page only. Violations still left add the warning
<N> markdown style violations left.- acceptance: Every fixture page passes fmlint with no violation.
-
7.1.5.5.6.
NOT_IMPLEMENTEDWhen violations are left, human stdout prints, before theNext: refineline,Next: fix the style violations listed by fiona-assistant mdoctor chklint <page path>.The page must passwiki sanitybefore it is refined. The JSONwarningstext does not change.- acceptance: An HTML fixture with a bare URL that the fixer leaves prints that line with the page path. A clean fixture does not.
-
- 7.1.5.6. Record. A run that archives appends one
bullet to
wiki/log.mdand bumps that file's patchversionandupdated. The bullet is- <YYYY-MM-DD> - ingest <origin> -> <raw path> -> <page path> (raw), or ends-> <raw path> (no page)when no page was written. The tool does not editwiki/index.mdor any other page.-
acceptance: One successful run adds one line to
log.mdand leavesindex.mdunchanged. -
7.1.5.6.1.
NOT_IMPLEMENTEDThe bullet passes the wiki's own markdownlint. The origin is a code span, so a URL is not a bare URL (MD034). Each->part starts a continuation line indented two spaces, so no line is longer than the bullet's longest path:- <YYYY-MM-DD> - ingest `<origin>` -> <raw path> -> <page path> (raw)The bullet still counts as one entry for 3.3.4. and the first acceptance above.
- acceptance: After ingesting a URL of 90 characters into a
fresh wiki,
wiki sanityreports no markdownlint hit inwiki/log.md.
- acceptance: After ingesting a URL of 90 characters into a
fresh wiki,
-
- 7.1.5.7.
--raw-onlyruns fetch, archive, and record, and skips convert and write. It exits 0.- acceptance: No page is written and
conversionisnone.
- acceptance: No page is written and
- 7.1.5.8.
--dry-runfetches into a temporary directory outside the wiki, so a URL is still downloaded. It printsDry run - no files will be modified:and then the lines a real run would print. It writes nothing under the wiki, does not move the source, and deletes the temporary directory.dry_runis true in JSON.- acceptance: File hashes under the wiki match before and after
a dry run, and an
ingest/source is still in place. - 7.1.5.8.1.
NOT_IMPLEMENTEDA dry run logs no record that says a file was archived, moved, or written. Those records readdry run: would archive <raw path>anddry run: would write <page path>.- acceptance: A dry run at
LOG_LEVEL=INFOhaswould archiveon stderr and no line that starts witharchivedafter the logger name.
- acceptance: A dry run at
- acceptance: File hashes under the wiki match before and after
a dry run, and an
- 7.1.5.9.
--pendinglists every page underwiki/whose frontmatterstatusisraw, sorted by path, and exits 0.- acceptance: A page changed to
status: refinedis no longer listed.
- acceptance: A page changed to
- 7.1.5.10. Refinement is the agent's phase. The
tool never writes
status: refined. A page is refined whenstatusisrefined,versionis1.0.0or later, the quality signals are set andllm.modelis notnone, the page is listed inwiki/index.md, andwiki/log.mdhas a line for the refinement.NOT_IMPLEMENTEDIt is also underwiki/, notrefine/(7.1.5.15.6.).- acceptance: Fiona skill section 18 lists those conditions and the steps that meet them, and says when to convert a source by hand.
- 7.1.5.11. The agent checks the frontmatter the
tool wrote before it refines the body. It may correct
title,type,tags,source_meta,ingest.conversion, andingest.warningswhen the source shows they are wrong. It does not hand-editingest.sha256,ingest.size_bytes,ingest.fetched,ingest.media_type, oringest.tool. When one of those is wrong, it re-runs the ingest with--forceor reports the fault to the user.- acceptance: Fiona skill section 18 has a metadata check step that names the fields it may edit and the fields it may not.
- 7.1.5.12. Archived sources do not fail
wiki sanity. Every check skipsraw/.- acceptance: After ingesting a markdown file with style
violations,
wiki sanityreports none from its raw copy.
- acceptance: After ingesting a markdown file with style
violations,
- 7.1.5.13.
--jsonprints only the JSON object from section 4.7.6 on stdout, on exit 0 and on exit 3. On exit 1 and exit 4, stdout is empty.- acceptance: The stdout of an exit 3 run parses with
json.loadsand hasconversion: none.
- acceptance: The stdout of an exit 3 run parses with
- 7.1.5.14. On exit 4 the agent gets the source
another way, or asks the user for it. The Fiona skill teaches
this in section 18.3. The steps, in order:
- 7.1.5.14.1. Use a tool the agent already has that can read
that host with the user's access, such as an MCP server for
Confluence, SharePoint, Jenkins, or a ticket system, or an
authenticated API script in the wiki's
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 and--origin <url>. - 7.1.5.14.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 the agent will run once the file is there. Do not retry the URL. - 7.1.5.14.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.
- 7.1.5.14.4. A tool that returns a summary instead of the
source is not the source. Archive the content the tool
returned as it is, and say in
ingest.warningsthat it came through that tool. - acceptance: Fiona skill section 6.7 lists exit 4. Section 18.3
has the three cases above (a tool with access, ask the user,
never ask for credentials) and shows the
--origincommand.
- 7.1.5.14.1. Use a tool the agent already has that can read
that host with the user's access, such as an MCP server for
Confluence, SharePoint, Jenkins, or a ticket system, or an
authenticated API script in the wiki's
- 7.1.5.15.
NOT_IMPLEMENTEDStaging inrefine/. The Write stage puts the raw page underrefine/at the wiki root, not underwiki/.refine/is the staging area between the tool's phase and the agent's. Nothing in it is part of the wiki yet. The agent refines a page there, then moves it intowiki/. Sowiki/holds only refined pages, and an unfinished ingest stays visible in one place. When built, this replaces thewiki/page path of 7.1.5.5.1., the existing-page check of 7.1.5.5.2., the--pendinglist of 7.1.5.9., and the housekeepingingeststep of 7.2.4..- 7.1.5.15.1.
NOT_IMPLEMENTEDA staged page mirrors its place in the wiki. The page forwiki/<rel>is staged atrefine/<rel>.<rel>comes from 7.1.5.5.1. unchanged:<default_target>/<slug>.md, or the-t/--targetvalue. That value still names the page's final place underwiki/and is checked againstwiki/as before. Both paths sit at the same depth, so a relative link resolves to the same target from either.- acceptance: A default ingest writes
refine/sources/<slug>.md, and its link../../raw/articles/<slug>.htmlresolves.-t conceptswritesrefine/concepts/<slug>.md.-t ../raw/x.mdand-t index.mdstill exit 1. Underwiki/, onlywiki/log.mdchanges.
- acceptance: A default ingest writes
- 7.1.5.15.2.
NOT_IMPLEMENTEDReports name the staged path. TheWrote:line, the JSONpage_path, and the log bullet of 7.1.5.6. userefine/<rel>. The last stdout line isNext: refine refine/<rel>, then move it to wiki/<rel>.- acceptance:
--jsonpage_pathstarts withrefine/, and the log bullet ends-> refine/<rel> (raw).--dry-runprints the same path and writes nothing.
- acceptance:
- 7.1.5.15.3.
NOT_IMPLEMENTEDAn existing page atwiki/<rel>orrefine/<rel>exits 1 unless--forceis set, with the 7.1.5.5.2. message naming the page found,wiki/<rel>first. With--force, the run writesrefine/<rel>and never writes or deleteswiki/<rel>. A refined page changes only when the agent merges the staged page into it (7.1.5.15.6.).- acceptance: With a refined
wiki/sources/a.md, a second ingest of its source exits 1 and nameswiki/sources/a.md. With--forceit writesrefine/sources/a.md, and the bytes ofwiki/sources/a.mdare unchanged.
- acceptance: With a refined
- 7.1.5.15.4.
NOT_IMPLEMENTEDThe duplicate check of 7.1.5.3.5. looks at pages underrefine/and underwiki/.duplicate_pageis the path where the match was found.- acceptance: A second ingest of the same bytes while the first
page is still staged reports
duplicate_page: refine/sources/<slug>.mdand writes nothing.
- acceptance: A second ingest of the same bytes while the first
page is still staged reports
- 7.1.5.15.5.
NOT_IMPLEMENTED--pendinglists every markdown page underrefine/exceptrefine/README.md, whatever itsstatus. Then it lists every page underwiki/withstatus: raw, left there by an older version. Each group is sorted by path.- acceptance: One staged page and one
status: rawpage underwiki/giveRaw pages: 2, the staged page first.
- acceptance: One staged page and one
- 7.1.5.15.6.
NOT_IMPLEMENTEDPromotion is the agent's step. The tool never moves a page out ofrefine/. 7.1.5.10. adds one condition: a refined page is underwiki/. The agent refinesrefine/<rel>to every other condition of 7.1.5.10., moves it towiki/<rel>, and deletes any directory underrefine/that the move left empty. Whenwiki/<rel>already exists, as after a--forcere-ingest, the agent merges the staged page into it instead. The merge keepscreated, bumpsversion, adds the new raw path tosources, and then deletes the staged page.- acceptance: Fiona skill section 18 has the move step and the
merge step, and says a refined page is never under
refine/.
- acceptance: Fiona skill section 18 has the move step and the
merge step, and says a refined page is never under
- 7.1.5.15.7.
NOT_IMPLEMENTEDA staged page writes each link as it resolves fromwiki/<rel>, so../concepts/x.mdmeanswiki/concepts/x.md.wiki sanitytherefore skipsrefine/in markdownlint and mdlinter. fmlint still checks it, so every staged page keepsnameandversion. A page underwiki/that links intorefine/is a dead link (MDL001) as before.- acceptance: A staged page with an MD013 hit and a link
../concepts/x.mdthat exists only aswiki/concepts/x.mdgives no markdownlint and no mdlinter violation. The same page withoutversiongives an fmlint violation.
- acceptance: A staged page with an MD013 hit and a link
- 7.1.5.15.8.
NOT_IMPLEMENTEDwiki graphomitsrefine/, the same way it omits a path infiona.wiki.graph.ignore_files(7.1.4.20.).wiki searchalready omits it, because its default scope iswiki/**/*.md(7.1.6.1.1.).- acceptance: A staged page is absent from the graph JSON
nodes, and it is not an orphan in housekeeping.
- acceptance: A staged page is absent from the graph JSON
- 7.1.5.15.9.
NOT_IMPLEMENTEDThe housekeepingingeststep isWARNwhen any page below exists, with one detail and one action per page, andPASSotherwise:- 7.1.5.15.9.1. A page under
refine/withoutstatus: refined: detailstaged: refine/<rel>, actionRefine refine/<rel>, then move it to wiki/<rel>. - 7.1.5.15.9.2. A page under
refine/withstatus: refined: detailready: refine/<rel>, actionMove refine/<rel> to wiki/<rel>., orMerge refine/<rel> into wiki/<rel>.when that page exists. - 7.1.5.15.9.3. A page under
wiki/withstatus: raw: detailraw in wiki: wiki/<rel>, actionMove wiki/<rel> to refine/<rel> and refine it there. - acceptance: One page of each kind gives
WARNand three details, each with its action.refine/README.mdalone givesPASS.
- 7.1.5.15.9.1. A page under
- 7.1.5.15.10.
NOT_IMPLEMENTEDThe template shipsrefine/README.md, with frontmatternameandversion, which says what the directory is for.refine/is a core directory (3.2.) and is not read-only.wiki updateaddsrefine/README.mdwhen it is missing and never touches a staged page.refine/is not in.gitignore, sogit savekeeps staged work. The templateAGENTS.mdboundaries and thewiki/schema.mddirectory tree namerefine/.- acceptance: After
wiki init,git ls-fileslistsrefine/README.md.wiki updateon a wiki withoutrefine/adds that file and nothing else underrefine/. The templateAGENTS.mdandwiki/schema.mdboth containrefine/.
- acceptance: After
- 7.1.5.15.1.
7.1.6. wiki search
Status: Planned
Implements section 4.7.7. A plain keyword search over the wiki, so the agent and the user find the lines that mention a term without reading whole pages. It reads files and writes nothing.
- 7.1.6.1.
NOT_IMPLEMENTEDFiles searched.- 7.1.6.1.1. By default the search covers every
*.mdfile underwiki/. Each--include GLOBis relative to the wiki root, may repeat, and replaces that default. So--include "raw/**/*.md" --include "wiki/**/*.md"searches both. - 7.1.6.1.2. A file is read as UTF-8 with any BOM stripped. Bytes that do not decode are replaced, and the file is still searched. Frontmatter lines are searched like any other line.
- 7.1.6.1.3. Files are visited sorted by their relative path, and lines in file order.
- acceptance: With a match in
wiki/a.mdand inraw/b.md, the default prints onlywiki/a.md. With--include "**/*.md"both print,raw/b.mdfirst.
- 7.1.6.1.1. By default the search covers every
- 7.1.6.2.
NOT_IMPLEMENTEDMatching.- 7.1.6.2.1. A keyword is a literal substring, not a regex. The
match ignores case unless
--case-sensitiveis set. - 7.1.6.2.2. A line matches when it holds any keyword. With
--all-words, it matches only when it holds every keyword. - 7.1.6.2.3. An empty keyword, or one that is only whitespace,
exits 1 with
Error: Empty keyword. - acceptance: For the line
Agent Harness works,harnessmatches,harness --case-sensitivedoes not,harness evalmatches, andharness eval --all-wordsdoes not.a.bdoes not matchaxb.
- 7.1.6.2.1. A keyword is a literal substring, not a regex. The
match ignores case unless
- 7.1.6.3.
NOT_IMPLEMENTEDOutput. Each matching line prints once, as<path>:<line>: <text>, even when it holds several matches. The last line isMatches: <N> lines in <F> files.- acceptance: Two matches on line 7 of
wiki/a.mdprint one line that starts withwiki/a.md:7:and one space, and the summary isMatches: 1 lines in 1 files.
- acceptance: Two matches on line 7 of
- 7.1.6.4.
NOT_IMPLEMENTEDLong lines.<text>is the line with leading and trailing whitespace removed. When it is longer thanfiona.wiki.search.max_line_chars, it is shortened around the first match on that line:- 7.1.6.4.1. The window is that many characters, minus room for the markers below. It holds the whole first match and splits the remaining room evenly before and after it. When one side reaches the start or end of the line, the other side takes the unused room.
- 7.1.6.4.2. A window edge that falls inside a word moves to the nearest space inside the window, unless that would cut the match.
- 7.1.6.4.3. The marker
...and one space start the text when the window does not start the line. One space and...end it when the window does not end the line. The result, with markers, is no longer thanmax_line_chars. - 7.1.6.4.4. When the match alone is longer than the window, the window starts at the match and is cut at its end.
- acceptance: With
max_line_chars40 and a 200-character line whose only matchharnessstarts at column 100,<text>has both markers, is at most 40 characters, and holdsharnesswhole. The text between the markers starts and ends on a whole word. - acceptance: With the match in the first 10 characters of that
line,
<text>starts with the line's first word, has no start marker, and has the end marker. - acceptance: A line of 40 characters or fewer prints unchanged.
- 7.1.6.5.
NOT_IMPLEMENTEDLimit. Only the firstfiona.wiki.search.max_resultsmatch lines print. When more exist, the line... <N> more matches. Narrow the keywords or raise max_results.follows them. The summary and the JSONtotalcount every match, and JSONtruncatedistrue.- acceptance: With
max_results2 and five matching lines, two match lines print, then... 3 more matches. ..., thenMatches: 5 lines in <F> files.
- acceptance: With
- 7.1.6.6.
NOT_IMPLEMENTEDThe command writes no file and nowiki/log.mdline.- acceptance: Every file under the wiki has the same bytes and modification time after a search.
7.2. housekeeping
Status: Partially Implemented
Implements section 4.8. Housekeeping is the routine an LLM runs to maintain a wiki. It gathers what needs work; the LLM does the work. Paths in details and actions are relative to the wiki root.
-
7.2.1. The steps run in this order:
check-update,merge,ingest,sanity,graph. Every step runs, even after a step fails.- acceptance: A wiki with a pending update file and a dead link
reports
mergeandsanityasFAIL, andgraphstill runs.
- acceptance: A wiki with a pending update file and a dead link
reports
-
7.2.2.
check-updateruns the check of 7.1.2. and writes nothing. It isPASSwhen nothing needs an update, a conflict, or an addition, andWARNotherwise. Its summary is<U> update(s), <C> conflict(s), <A> addition(s). Each item is a detail line:update: <path>,conflict: <path> -> <update path>, oradd: <path>. The action isAsk the user, then run fiona-assistant wiki update --dry-run and wiki update --yes.- acceptance: An
AGENTS.mdolder than the template givesWARNand the detailconflict: AGENTS.md -> AGENTS-update.md, and no update file is written.
- acceptance: An
-
7.2.3.
mergelists every file whose stem ends with-updateoutsidepersonal/,raw/, and.git/, except a path matched byfiona.wiki.update.ignore_filesand exceptcorefiles.json(7.1.2.15.). That includesfiona-settings-update.json. It isFAILwhen one such file exists. Each detail is<update path> -> <target path>, followed by a space and(target missing)when the target is absent. The target is the same name without-update. The action per file is:Merge <update path> into <target path>: keep the owner's edits, take the template changes, set version to at least <template version>, then delete <update path>.<template version>is the update file'sversion, or the textthe template versionwhen it has none.- acceptance: A
wiki/schema-update.mdat1.5.0gives the detailwiki/schema-update.md -> wiki/schema.mdand an action that names1.5.0. - acceptance:
fiona-settings-update.jsongives the detailfiona-settings-update.json -> fiona-settings.json. - acceptance:
corefiles.jsonat the wiki root is not a detail. Anotes-update.mdwhose path is inignore_filesis not a detail.
- acceptance: A
-
7.2.4.
ingestlists the markdown pages underwiki/whose frontmatter hasstatus: raw. It isWARNwhen one exists, with one detail per page and the actionRefine each raw page, then set status: refined.NOT_IMPLEMENTED7.1.5.15.9. replaces this step once staging is built.- acceptance: A page with
status: rawisWARNand named in the details. With none, the step isPASS.
- acceptance: A page with
-
7.2.5.
sanityruns the checks of 7.1.3. without the progress display. It isFAILwhen any check has a violation. The summary is<N> violation(s) in <K> check(s). The details are each failing check's report lines. The action isFix the violations, then run fiona-assistant housekeeping again.- acceptance: One dead link makes the step
FAILand a detail line names the file. - 7.2.5.1.
NOT_IMPLEMENTEDThe details are one line per violation,<check>: <path>:<line>:<column> <code> <message>, with the path relative to the wiki root. Report headers, DEFINITIONS, and SUMMARY lines are not details. The full report stays withwiki sanity.- acceptance: A wiki with three MD013 hits and one dead link
gives exactly four
sanitydetail lines.
- acceptance: A wiki with three MD013 hits and one dead link
gives exactly four
- acceptance: One dead link makes the step
-
7.2.6.
graphwrites<wiki root>/wiki_graph.htmlwith the defaults of section 4.7.5 and the wiki's graph settings. The summary iswrote wiki_graph.html (<nodes> nodes, <edges> edges). A markdown page underwiki/with no inbound and no outbound link is an orphan: the step isWARN, one detailorphan: <path>per page, and the actionLink each orphan page from a related page or from wiki/index.md.Update files are not orphans. An error writing the graph isFAILwith the error as the detail.- acceptance: After the run
wiki_graph.htmlexists at the wiki root, and an unlinked page underwiki/is named as an orphan.
- acceptance: After the run
-
7.2.7. Housekeeping writes only
wiki_graph.html. It does not runwiki update, merge an update file, or fix a violation.- acceptance: Apart from
wiki_graph.html, every file hash is unchanged after a run.
- acceptance: Apart from
-
7.2.8.
Next steps:lists each step's actions in step order, without repeats.passedis true when no step isFAIL.- acceptance:
--jsonstdout parses withjson.loads, and a wiki with onlyWARNsteps haspassed: trueand exit 0.
- acceptance:
7.3. librarian
Requirements for librarian.
7.3.1. Folder and In-file TOC
Status: Implemented
- 7.3.1.1. Folder TOC (
librarian toc).- 7.3.1.1.1.
table_of_contents.mdhas frontmattername,version,title,created,updated, andtype: toc.nameisTable of Contentsandversionis1.0.0. - 7.3.1.1.2. Entries list subfolders, file links, and
v<version>, orv0.0.0when version is missing or unreadable. - 7.3.1.1.3. Headers become nested GitHub-style anchor links.
Fenced code is not scanned. Files are read as
utf-8-sigso a BOM does not hide the first header. The anchor is the header text lowercased, with every character that is not a word character, space, or-removed, and then each space replaced by one-. Runs of spaces are not collapsed, so the anchor matches the one PyMarkdown MD051 and Markdown previews resolve.- acceptance:
Training | XXXXXXX-x-xxxx DONEhas the anchortraining--xxxxxxx-x-xxxx-done, andtimeout / cannothastimeout--cannot.
- acceptance:
- 7.3.1.1.4. Skip the TOC file itself, hidden folders, and
--excludematches. - 7.3.1.1.5.
--recursive-tocwrites a TOC in every subfolder. - 7.3.1.1.6.
--non-recursivelists only markdown files directly in the folder, ignoringmax_depth_from_dir. - 7.3.1.1.7.
max_depth_from_fileis the deepest header level (3 lists h1 through h3).max_depth_from_diris how many subfolder levels to include (1includes the folder and its children). Absent or0means unlimited. Any other non-integer or negative value exits 1 and names the key.
- 7.3.1.1.1.
- 7.3.1.2. In-file TOC (
librarian toc file).-
7.3.1.2.1. Insert directly under the H1, after frontmatter. The H1 itself is not listed. Headings inside fences are not listed. A
#inside frontmatter is not the H1. -
7.3.1.2.2. The block is wrapped in these markers.
sectionizedis present only when numbering was on.<!-- toc-start: headings 2..6 --> <!-- toc-end -->Example with numbering:
<!-- toc-start: sectionized, headings 2..6 -->. -
7.3.1.2.3. On regeneration, marker parameters win, then
--sectionized, then settings. Asectionizedmarker keeps numbering. The recorded heading range stays, so a later settings change does not retarget an existing TOC. A bare<!-- toc-start -->has no parameters and is upgraded on regeneration. An invalid range is ignored with a warning. -
7.3.1.2.4. The block is replaced in place. A current block is reported unchanged and not rewritten. Blank lines separate the markers from the list so MD032 passes.
-
7.3.1.2.5. When
sectionizeis true, entries and heading lines gain numbers such as1.1.. Existing numbers are stripped before renumbering so anchors still match. -
7.3.1.2.6.
toc file *root is the nearestfiona-settings.json, current directory first, then subdirectories. Skip hidden folders andbuild/,dist/,__pycache__/,*.egg-info/. If none is found, use the current directory. -
7.3.1.2.7.
toc file *skips read-only zones, hidden files and folders,table_of_contents.md, andignore_filesmatches. -
7.3.1.2.8.
toc file <explicit path>insidepersonal/orraw/, or a missing or non-markdown path, exits 1 and writes nothing.
-
- 7.3.1.3. Two markdown files in a folder produce one TOC that
lists both versions and their headers, and omits a header that
sits inside a fence.
- acceptance: The fence header's anchor is absent.
- 7.3.1.4.
max_depth_from_file: 3omits####and lists###. Absent or0lists every level.- acceptance: The
####line is absent only in the capped run.
- acceptance: The
- 7.3.1.5.
max_depth_from_dir: 1omits files two levels down. Absent or0lists them.--non-recursivelists only the folder's own files.- acceptance: The deep file is absent in both limited modes.
- 7.3.1.6. Re-running
toc filereplaces the marked block and does not append a second TOC.- acceptance: The file contains one
toc-startmarker.
- acceptance: The file contains one
- 7.3.1.7.
min_heading: 3omits##.max_heading: 3omits####.- acceptance: Each setting hides only its out-of-range level.
- 7.3.1.8. An
ignore_filesmatch is not modified bytoc file *. An explicit path inpersonal/exits 1 and is unchanged.- acceptance: Both files keep their original bytes.
7.3.2. Non-markdown Version Tags
Status: Planned
- 7.3.2.1.
NOT_IMPLEMENTEDPython and shell files gain a version tag. The tag format is undecided (Appendix C). Do not implement until that format is chosen.- acceptance: The format is written in this spec before any scanner ships.
7.3.3. Move with Link Rewrite
Status: Planned
Implements section 4.1.2. In this section a link is one of:
- an inline link
[text](path) - an image
 - a reference definition
[id]: pathat the start of a line, after up to three spaces
A relative link holds a path relative to the folder of the file
that contains it. A markdown file is a file whose suffix is .md,
in any case.
- 7.3.3.1.
NOT_IMPLEMENTEDSource and target.- 7.3.3.1.1.
<source>is an existing file or folder. - 7.3.3.1.2. When
<target>is an existing folder, the final path is<target>/<source name>. Otherwise<target>is the final path. Missing parent folders of the final path are created. - 7.3.3.1.3. A folder source moves every file under it, hidden files included, and keeps their layout relative to the folder. The emptied source folder is removed.
- acceptance:
move wiki/a.md wiki/concepts/with an existingwiki/concepts/createswiki/concepts/a.mdand removeswiki/a.md. - acceptance:
move wiki/a.md wiki/new/b.mdwith nowiki/new/createswiki/new/andwiki/new/b.md. - acceptance:
move wiki/notes wiki/archive/notesmoveswiki/notes/x.mdandwiki/notes/img/p.pngto the same relative places, andwiki/notes/no longer exists.
- 7.3.3.1.1.
- 7.3.3.2.
NOT_IMPLEMENTEDRefusals. Each prints its line on stderr, writes nothing, and exits 1.- 7.3.3.2.1. Missing source:
Error: '<source>' does not exist. - 7.3.3.2.2. The final path exists:
Error: '<final path>' already exists. - 7.3.3.2.3. The final path is the source, or lies inside a
folder source:
Error: cannot move '<source>' into itself. - 7.3.3.2.4. The source, or the final path, is inside
personal/orraw/of the wiki root (1.2.3.). The wiki root is found as in 7.3.1.2.6.:Error: '<path>' is in a read-only zone. - acceptance: Each refusal leaves every file under the wiki root byte-identical and creates no folder.
- 7.3.3.2.1. Missing source:
- 7.3.3.3.
NOT_IMPLEMENTEDOutbound links in each moved markdown file are rewritten.- 7.3.3.3.1. The link path is percent-decoded and resolved against the file's old folder. When it names an existing file or folder, the new path is the relative path from the file's new folder to that target's location after the move. A target moved in the same run counts at its new location.
- 7.3.3.3.2. The new path uses
/. A#fragmentand a?queryare kept as written. A link title ("t",'t', or(t)) is kept. A path written in<...>stays in<...>. A leading./is kept when the old path had one. Outside<...>, a space is written as%20. - 7.3.3.3.3. A link whose new text equals the old text is not rewritten and not counted.
- acceptance:
wiki/a.mdholds[b](b.md#x)and. Aftermove wiki/a.md wiki/concepts/a.mdthe file holds[b](../b.md#x)and, and stdout hasrewrote 2 link(s) in wiki/concepts/a.md. - acceptance:
wiki/notes/a.mdlinksb.md(a sibling) and../index.md. Aftermove wiki/notes wiki/archive/notes,b.mdis unchanged and../index.mdbecomes../../index.md. - acceptance:
[d]: ../docs/My%20File.mdkeeps its%20after the rewrite.
- 7.3.3.4.
NOT_IMPLEMENTEDThese stay byte-identical:- 7.3.3.4.1. External links: any path with a URI scheme
(
http:,https:,mailto:, or<scheme>://). - 7.3.3.4.2. Pure anchors (
#section) and absolute paths (a leading/, or a Windows drive letter). - 7.3.3.4.3. Wikilinks
[[page]]. They resolve by stem, so a move that keeps the file name does not change them. A rename is 7.3.3.6.3. - 7.3.3.4.4. Text inside fenced code and inline code, HTML
tags such as
<a href>and<img src>, and autolinks<https://...>. - 7.3.3.4.5. Frontmatter.
sources:paths are relative to the wiki root, not to the file. - 7.3.3.4.6. A relative link that did not resolve before the
move. It is counted on an
unresolvedline. - acceptance: A moved file that holds one example of each item
above differs from the original only in its rewritten links,
and a dead link adds
unresolved 1 link(s) in <path>.
- 7.3.3.4.1. External links: any path with a URI scheme
(
- 7.3.3.5.
NOT_IMPLEMENTEDA file that is moved or rewritten keeps everything that is not a rewritten link: encoding, a UTF-8 BOM, line endings, the final newline, and frontmatterversionandupdated. A file that is not markdown moves byte for byte.- acceptance: A CRLF markdown file still has CRLF endings after the move, and a moved PNG has the same SHA-256.
- 7.3.3.6.
NOT_IMPLEMENTEDInbound links. The command searches the whole wiki for references to the moved paths and points them at the new paths, so the move leaves no dead link.- 7.3.3.6.1. The search covers every markdown file under the
wiki root (7.3.1.2.6.) that did not move. Hidden folders
(
.gitincluded) are skipped. - 7.3.3.6.2. A relative link in such a file that resolves, before the move, to the source, or to any file or folder under a folder source, is rewritten to the relative path from that file's folder to the new location. 7.3.3.3.2. and 7.3.3.3.3. apply. 7.3.3.4. applies, except its last item: a link that does not point at a moved path is left alone and is not counted as unresolved.
- 7.3.3.6.3. When a moved markdown file changes its stem,
every wikilink in the wiki, in moved files too, whose target
equals the old stem (case-insensitive, as MDL002 matches) is
rewritten to the new stem. A
#sectionand a|labelare kept. A wikilink is left alone when another markdown file in the wiki still has the old stem after the move. - 7.3.3.6.4. A file inside
personal/orraw/is never written (1.2.3.). Each of its links that point at a moved path is counted on aread-onlyline, so the user sees what will be dead. - 7.3.3.6.5. A file with nothing to rewrite stays byte-identical.
- acceptance:
wiki/index.mdholds[a](a.md#top). Aftermove wiki/a.md wiki/concepts/a.mdit holds[a](concepts/a.md#top), and stdout hasrewrote 1 link(s) in wiki/index.md. - acceptance:
wiki/log.mdlinksnotes/x.mdandnotes/img/p.png. Aftermove wiki/notes wiki/archive/notesthose links arearchive/notes/x.mdandarchive/notes/img/p.png. - acceptance:
wiki/index.mdholds[[a#intro|A page]]. Aftermove wiki/a.md wiki/b.mdit holds[[b#intro|A page]]. Whenwiki/other/a.mdalso exists, the wikilink is unchanged. - acceptance:
raw/n.mdlinks../wiki/a.md. After the moveraw/n.mdis byte-identical and stdout hasread-only 1 link(s) in raw/n.md. - acceptance: After a move with no
read-onlyand nounresolvedline,wiki sanityreports no MDL001 or MDL002 that the move caused.
- 7.3.3.6.1. The search covers every markdown file under the
wiki root (7.3.1.2.6.) that did not move. Hidden folders
(
- 7.3.3.7.
NOT_IMPLEMENTEDOrder of work: check every refusal, compute every rewrite, then move and write.--dry-runstops after the compute step and prints the same lines a real run prints, each with the[dry-run]prefix. AnOSErrorduring the write step printsError: <message>on stderr and exits 1.- acceptance:
--dry-runleaves the tree byte-identical, and its stdout equals the stdout of the real run with each line prefixed.
- acceptance:
- 7.3.3.8.
NOT_IMPLEMENTEDThe command runs no git operation. The wiki records the move withgit save(3.3.3.).- acceptance: In a git wiki the commit count is the same before
and after
move.
- acceptance: In a git wiki the commit count is the same before
and after
7.4. mdoctor
Status: Partially Implemented
Implements section 4.2 and the pymarkdown keys in section 5.1.
Settings load at construction. The default settings path is the
packaged template fiona-settings.json. Callers, including
run_sanity.py, may pass another path. A missing file means plain
pymarkdown defaults.
- 7.4.1.
mdoctor fixrepairs an auto-fixable violation such as MD047 and lists the path.- acceptance: The file ends with a newline and stdout contains
PyMarkdownFix: 1 file(s) fixed.
- acceptance: The file ends with a newline and stdout contains
- 7.4.2. A tree with nothing to fix prints
PyMarkdownFix: 0 file(s) fixed.- acceptance: That line is the only stdout line.
- 7.4.3. A scan does not ask PyMarkdown to run git. When
respect_gitignoreis true and the path is inside the working directory, directory names from.gitignoreand.gitare exclude patterns. A path outside the working directory is still skipped by the directory-name check after the scan.respect_gitignorefalse still scans those directories, except.gitwhen the path is inside the working directory.- acceptance:
scan_pathis called withrespect_gitignorefalse. Inside the working directory the exclude list contains.git/and each plain directory name from.gitignore.
- acceptance:
- 7.4.4.
NOT_IMPLEMENTEDchklintandfixaccept one markdown file as well as a directory, the same asfmlint chklint. A path that does not exist printsError: '<path>' does not exist.on stderr and exits 1.- acceptance:
mdoctor fix wiki/sources/a.mdlists only that file, and every other file hash is unchanged.
- acceptance:
7.5. fmlint
Status: Implemented
Implements sections 4.3 and 6.2.
- 7.5.1.
required_fieldsin settings replaces the default pair on the next run.- acceptance: Adding
titleto the list reports a file that previously passed.
- acceptance: Adding
- 7.5.2.
enabled: falsereports no frontmatter violations.- acceptance: A file with no frontmatter is clean for fmlint.
- 7.5.3. A code in
ignore_rulesis omitted. A glob inignore_fileskips those paths.- acceptance:
ignore_rules: ["FML002"]hides a missing-block finding and still reports a missingname.
- acceptance:
7.6. mdlinter
Status: Implemented
Implements section 6.3. Checks run in registry order. A new check
is a method plus an entry in that registry. lint_file resolves
wikilinks against the file's parent tree. lint_directory scans
the wiki.
- 7.6.1. The report header is
Markdown Lint Violationsand the section order matches section 6.1.- acceptance: DEFINITIONS lists
MDL001: Dead Linkwhen a dead markdown link exists.
- acceptance: DEFINITIONS lists
7.7. pycustomlint
Status: Implemented
Implements section 6.4. The sanity runner in section 7.14 includes
it as pycustomlint. There is no fiona-assistant pycustomlint
command; the repository runner calls the library.
- 7.7.1.
--jsonprints a JSON list of violation objects.- acceptance:
json.loadssucceeds and each object hascode.
- acceptance:
7.8. python-ruff
Status: Implemented
Implements section 4.4. The sanity check name is ruff in
run_sanity.py and python-ruff in wiki sanity.
- 7.8.1. An unused import appears in DEFINITIONS, FILE, and
SUMMARY.
- acceptance: The FILE line contains the ruff rule code.
- 7.8.2.
NOT_IMPLEMENTEDApython-ruff fixsubcommand mirrorsmdoctor fixand calls the existingfix=Truepath.- acceptance: An auto-fixable ruff finding is gone after the command and the path is listed.
7.9. Shellcheck
Status: Planned
- 7.9.1.
NOT_IMPLEMENTEDWrap theshellcheckbinary and print the shared report.- acceptance: A known shellcheck finding shows file, line, and rule code.
- 7.9.2.
NOT_IMPLEMENTEDA missing binary prints an install hint and exits non-zero, with no traceback.- acceptance: The message names
shellcheck.
- acceptance: The message names
- 7.9.3.
NOT_IMPLEMENTEDWiki sanity runs this check.- acceptance: The
Results:table includes the new check name.
- acceptance: The
7.10. Markdown Code Blocks
Status: Planned
- 7.10.1.
NOT_IMPLEMENTEDExtract fenced blocks. Lint Python blocks with Ruff and shell blocks with shellcheck. Skip other languages.- acceptance: An unused import inside a Python fence is reported. Prose outside fences is not.
- 7.10.2.
NOT_IMPLEMENTEDThe finding names the markdown path, the fence index, the line inside the fence, and the markdown line number.- acceptance: The reported markdown line is the fence line that contains the import.
- 7.10.3.
NOT_IMPLEMENTEDWiki sanity runs this check.- acceptance: The check appears in the
Results:table.
- acceptance: The check appears in the
7.11. json-lint
Status: Implemented
Implements sections 4.5 and 6.5. Both sanity runners include it.
- 7.11.1. A JSON violation fails
run_sanity.pyand wiki sanity.- acceptance: The
Results:row forjsonlintis FAIL and the process exit code is non-zero.
- acceptance: The
- 7.11.2. An empty tree of JSON files prints no violations.
- acceptance: The report says no violations were found.
7.12. Git Operations
Status: Implemented
Implements section 4.6. wiki init writes the repository
.gitignore patterns and personal/ (section 7.1.1). Those paths
are never staged by these commands except where git add --all
respects that ignore file.
- 7.12.1.
save --description noteon a dirty tree creates one commit whose message starts with the UTC timestamp and ends withnote.- acceptance:
git log -1 --format=%smatches<YYYY-MM-DD HH:MM:SS> note.
- acceptance:
- 7.12.2.
snapshot demo --description notethenrestore demoreturns file bytes to the tagged tree and adds a new commit. The pre-restore history is still reachable.- acceptance:
git rev-parse HEAD~1after restore is the snapshot commit or a descendant, and the tagged tree matches the worktree.
- acceptance:
- 7.12.3.
undoandrestoreon a dirty tree exit 1 and mentionclean.- acceptance: The HEAD sha is unchanged.
- 7.12.4.
cleanleavesgit statusempty of changes.- acceptance: A following
statusprintsStatus: clean.
- acceptance: A following
7.13. Backup Script
Status: Planned
- 7.13.1.
NOT_IMPLEMENTEDA bundled command writes a restorable archive of the wiki.- acceptance: Restoring that archive reproduces the wiki tree from before the archive.
- 7.13.2.
NOT_IMPLEMENTEDThe archive is stored outside the wiki tree.- acceptance: The archive path is not under the wiki root.
- 7.13.3.
NOT_IMPLEMENTEDThe filename isYYYYMMDD_hhmm_<description>.zstd.- acceptance: The file is valid zstd and the name matches.
- 7.13.4.
NOT_IMPLEMENTEDThe command asks for a directory and uses~/Downloadswhen the user accepts the default.- acceptance: Pressing Enter writes the archive under
~/Downloads.
- acceptance: Pressing Enter writes the archive under
7.14. Test and Sanity Runners
Status: Implemented
- 7.14.1. Shared engine, used by
run_sanity.pyand wiki sanity.- 7.14.1.1. One thread per check. Results stay in registry order.
- 7.14.1.2. Summary line
PASS/FAIL - <detail> (MM:SS). Minutes may exceed 59 and are zero-padded. A missing duration omits the suffix. - 7.14.1.3.
SANITY PASSED (MM:SS)lists check names in registry order.Sanity Failed - N checks need attention:has no total time. - 7.14.1.4. A runner may add an extra result row, such as coverage, and per-check failure details.
- 7.14.1.5.
progress(name, result)runs when a check finishes.heartbeat(remaining_names)runs about every 0.5 seconds. Start and finish are logged at INFO.
- 7.14.2. Progress display.
- 7.14.2.1. On a TTY, one bar per check, redrawn in place with
cursor-up and line clear. Example:
pytests [###------------] 22% 6.5s. - 7.14.2.2. The bar fills as elapsed /
expected-seconds, capped at 100%. - 7.14.2.3. A finished check shows a full bar and
(MM:SS):markdownlint [###############] 100% done (00:07). - 7.14.2.4. The final block stays on screen above the reports.
- 7.14.2.5.
--non-interactive, also when stdout is not a TTY, printsRunning SanityorRunning Wiki Sanityonce, then one dot perintervalseconds. A run shorter than the interval prints no dots. A newline ends the line before the report. No ANSI. - 7.14.2.6.
--jsonon wiki sanity skips the display. - 7.14.2.7. Bar scale and dot interval come from section 5.2.
- 7.14.2.1. On a TTY, one bar per check, redrawn in place with
cursor-up and line clear. Example:
- 7.14.3.
run_tests.pyand the pytests check.- 7.14.3.1. The command includes
--color=noand JUnit XMLjunit_family=xunit1. - 7.14.3.2. Displayed messages prefer regex-parsed pytest output. JUnit fills missing fields and replaces empty messages. Match by basename plus test name so path spellings do not duplicate a failure.
- 7.14.3.3. A missing short summary logs a WARNING that names
PYTEST_ADDOPTS,--no-summary, and plugin output as likely causes. - 7.14.3.4.
LOG_LEVEL=DEBUGlogs the pytest command, return code, parsed failures, and raw output when the parse disagrees. - 7.14.3.5. The report nests failures as
Class : test_nameunder the file, then the assert text, or the exception text when there is no assert line. - 7.14.3.6. The
Sanity Failedverdict lists failing test names only. Assert text stays in the report body. - 7.14.3.7. The
coverage:line isPASS/FAIL - <percent>% (required <percent>%)and is untimed. A shortfall is its own verdict entry.
- 7.14.3.1. The command includes
- 7.14.4.
run_sanity.pycheck order ispytests,markdownlint,ruff,frontmatter_lint,pycustomlint,jsonlint. - 7.14.5. A failing test is listed under its file with the assert
text when pytest is run with
--no-summaryorPY_COLORS=1.- acceptance: The name and assert still appear.
- 7.14.6. A green run prints every
Results:line with(MM:SS)and ends withSANITY PASSED (MM:SS).- acceptance: The banner time is the wall time of the whole run.
- 7.14.7. A piped run contains no ANSI and prints one dot per
interval after the label, unless the run is shorter than the
interval.
- acceptance: The captured stdout has no ESC byte.
7.15. html-js-lint
Status: Planned
The html-js-lint console script is not installed until this
section is built. The intended tool validates HTML with
html5validator (Java 8+) and JavaScript with eslint on PATH.
-
7.15.1.
NOT_IMPLEMENTEDHTML files (default.htmland.htm) are checked. Findings include path, line, and column..gitignoreand read-only zones are skipped.- acceptance: An unclosed tag is reported. A valid file is not. A tree with no HTML prints no HTML findings.
-
7.15.2.
NOT_IMPLEMENTEDJavaScript files (default.jsand.javascript) are checked with eslint, honoring.eslintrc.- acceptance: A syntax error names path, line, and message. A clean file produces no finding.
-
7.15.3.
NOT_IMPLEMENTEDInline<script>is linted only whenhtml.lint_inline_jsis true (default false). Findings use the HTML path and line.- acceptance: With the flag off, inline script is ignored.
-
7.15.4.
NOT_IMPLEMENTEDCLI isfiona-assistant html-js-lint, defaultchklint ., shared report, exit 0 even with violations, and--fixwhere the underlying tool can fix.- acceptance:
--fixreports how many files changed.
- acceptance:
-
7.15.5.
NOT_IMPLEMENTEDSettings, under a dedicated section, with defaults when the section is missing:Key Default html.extensions["html", "htm"]html.ignore_patterns[]html.lint_inline_jsfalse javascript.extensions["js", "javascript"]javascript.eslint_config.eslintrcjavascript.ignore_patterns[]- acceptance: A custom extension list is the set that is scanned.
-
7.15.6.
NOT_IMPLEMENTEDBothrun_sanity.pyand wiki sanity run this check.- acceptance: A violation fails that sanity run.
7.16. settings setup
Status: Planned
fiona-assistant init remains the non-interactive wiki bootstrap
(section 7.1.1): it copies the template and does not ask questions.
fiona-assistant setup is a separate command for reviewing settings
on an existing wiki. It does not create the wiki tree.
- 7.16.1.
NOT_IMPLEMENTEDsetupwalks every configurable key infiona-settings.json, shows the current value, and accepts Enter as "keep current".- acceptance: Enter through every prompt leaves the file semantically unchanged.
- 7.16.2.
NOT_IMPLEMENTEDBooleans can be toggled. Strings and integers accept a typed value. Values are checked before write.- acceptance: A non-integer for
indent_lenis rejected and the file is not written.
- acceptance: A non-integer for
- 7.16.3.
NOT_IMPLEMENTED--yesor--defaultapplies defaults with no prompts.- acceptance: The command exits 0 on a pipe when the flag is set.
- 7.16.4.
NOT_IMPLEMENTEDA missing settings file is created from the template defaults. A corrupt file is reported and not silently replaced.- acceptance: Exit 0 after creating a missing file. Exit non-zero on corrupt JSON, with the parse error on stderr.
- 7.16.5.
NOT_IMPLEMENTEDsetupcan be run again later to change an existing wiki.- acceptance: A second run can change
log_leveland leave every other key as it was.
- acceptance: A second run can change
7.17. Logging
Status: Partially Implemented
The contract is section 2. Reports stay on stdout. Diagnostics go through the logging module to stderr and, when configured, to the file sink.
- 7.17.1. Each CLI entry calls the shared setup before doing work.
- acceptance:
LOG_LEVEL=DEBUGemits debug lines on stderr and the human report stays on stdout.
- acceptance:
- 7.17.2. Dropping
file_log_locationleaves no file handler.- acceptance: No log file is created for that run.
- 7.17.3.
NOT_IMPLEMENTEDThe shippedfiona-settings.jsonsetsfiona.log_leveltoWARNING, the same as the default in section 5.1.fiona.file_log_levelstaysINFO, sofiona.logkeeps the detail. PowerShell shows every native stderr line as aNativeCommandError, so anINFOrecord looks like a failure even when the exit code is 0. When this is built, the shipped document in section 5.1 changes to match.- acceptance: In a fresh wiki,
wiki sanityon the clean template andwiki ingestof a local markdown file write nothing on stderr, andfiona.loghas theirINFOlines.
- acceptance: In a fresh wiki,
7.18. Documentation
Status: Partially Implemented
README.md links to this spec. src/README.md,
src/fiona/librarian/README.md, and src/fiona/mdoctor/README.md exist and
are behind the current CLIs.
- 7.18.1.
NOT_IMPLEMENTEDlibrarian/README.mddocumentslistandtoc.mdoctor/README.mddocumentslist,chklint, andfix.- acceptance: A new reader can install and run each command from those files alone.
- 7.18.2.
src/README.mddescribessrc/fiona/(includingwiki/,python_ruff/, anddata/llm_wiki/), repo-roottests/, andscripts/(run_tests.py,run_sanity.py,settings_dev.json).- acceptance: Those names appear in the structure section.
- 7.18.3. Documentation markdown passes
mdoctor chklint.- acceptance:
README.mdcontains a markdown link toSPEC.mdand the lint report is clean.
- acceptance:
- 7.18.4.
NOT_IMPLEMENTEDThe README Quick Start has a short "After ingest" and "On Windows" part. It says that a file iningest/moves intoraw/and a second run on it fails, thatLOG_LEVEL=ERRORhides diagnostics until 7.17.3. ships, the loophousekeeping, then fix style violations, then refine and setstatus: refined, that--version(2.3.) orpip show fiona-assistantgives the installed version, and that commands run from the wiki root until section 7.20 is built. The Fiona skill carries the same loop.- acceptance: Each of those five points appears in
README.md, and the after-ingest loop appears in the Fiona skill.
- acceptance: Each of those five points appears in
7.19. Tool Roles
Status: Planned
- 7.19.1.
NOT_IMPLEMENTEDEachsrc/tool has one role: ingestion (ingest/toraw/), processing (raw/towiki/concepts/), or maintenance (index.md/log.mdand the linters).- acceptance: A table in this spec or the README assigns every tool exactly one role.
- 7.19.2.
NOT_IMPLEMENTEDIngestion iswiki ingest(section 7.1.5). Missing processing steps become scripts under the templateutils/directory, such asprocess.py.- acceptance: Each new script is named in the role table.
7.20. Wiki Root Discovery
Status: Planned
Today every optional directory defaults to .. toc file * already
searches for fiona-settings.json as specified in section 7.3.1.
Graph settings already walk parent directories. The dispatcher does
not.
- 7.20.1.
NOT_IMPLEMENTEDWhen the directory argument is omitted, commands use the wiki root from Appendix C's discovery rule.- acceptance:
fiona-assistant mdoctorfrom a subdirectory lints that root, not the subdirectory.
- acceptance:
- 7.20.2.
NOT_IMPLEMENTEDAn explicit directory always wins.- acceptance:
mdoctor chklint sub/dirlintssub/direven when a settings file exists higher up.
- acceptance:
- 7.20.3.
NOT_IMPLEMENTEDWith no settings file found, the default stays..- acceptance: Behavior matches today's commands.
- 7.20.4.
NOT_IMPLEMENTEDThe file is loaded once per process and shared. mdoctor already reads it for rules.- acceptance: Two tools in one invocation see the same object.
7.21. Bootstrap install modes
Status: Implemented
bootstrap (bash, sourced) and bootstrap.ps1 (PowerShell) prepare
a Python environment and install this repository. With no install
flag, both create or reuse a virtual environment and run
python -m pip install -e ".[dev]". scripts/bootstrap_install.py
is the pip-argument source both scripts call.
- 7.21.1.
--localinstalls this repository as a normal package. The pip arguments areinstalland.. They do not include-eand they do not include thedevextra.- acceptance:
pip_install_args(local=True, no_env=False)is["install", "."].
- acceptance:
- 7.21.2.
--no-envdoes not create or activate a virtual environment. The install adds--user, so the console scripts land in the user scripts directory and run without activating an environment.- acceptance:
pip_install_args(local=False, no_env=True)contains--user. PowerShell skips virtual environment creation when$NoEnvis set. Bash skips it whenNO_ENVistrue.
- acceptance:
- 7.21.3.
--localand--no-envcombine. The install isinstall,--user, and., with no-e.- acceptance:
pip_install_args(local=True, no_env=True)is["install", "--user", "."].
- acceptance:
- 7.21.4. Neither flag keeps the default:
-eand.[dev], and no--user.- acceptance:
pip_install_args(local=False, no_env=False)is["install", "-e", ".[dev]"].
- acceptance:
- 7.21.5. Bash adds
--break-system-packageson every install. PowerShell does not.- acceptance:
break_system_packages=Trueinserts that flag after--userwhen both are set, and afterinstallwhen--useris absent.
- acceptance:
- 7.21.6. A virtual-environment install on PowerShell must be
dot-sourced so the environment stays active.
--no-envmay be executed with-File, because there is no environment to keep active. Bash is sourced for both modes.- acceptance: PowerShell reports a dot-source error when
--localis used without--no-envand the script is not dot-sourced. The message does not call--localan unknown option.
- acceptance: PowerShell reports a dot-source error when
Appendix A. Non-Goals
- A.1. No LLM or network API inside Fiona-Assistant. The tools are deterministic.
- A.2. No automated edit of
personal/orraw/content.wiki ingestadds new files underraw/and edits none (1.2.3.). - A.3. No cloud sync and no remote backup. Version control is local. The planned archive in 7.13. is a local file.
- A.4. Deterministic tools make no cloud API calls. Each command
uses only local files and finishes with no network access.
- acceptance: With the network unavailable,
wiki sanityandwiki graphstill complete on a local wiki. - acceptance: Opening the generated graph HTML is an exception:
the browser loads D3 from
d3js.org(7.1.4.). The generator itself does not call that host. - acceptance:
wiki ingest <url>is the other exception. It downloads only the URL the user passed (7.1.5.2.). With a local path it makes no network call.
- acceptance: With the network unavailable,
Appendix B. Priority Order
| Priority | Feature | Section | Status |
|---|---|---|---|
| P1 | wiki update / check-update | 7.1.2 | Implemented |
| P1 | Git save, snapshot, restore, clean, undo, status | 7.12 | Implemented |
| P1 | wiki sanity, including dead links | 7.1.3 | Implemented |
| P1 | housekeeping | 7.2 | Partially Implemented |
| P1 | wiki init | 7.1.1 | Partially Implemented |
| P1 | CLI errors without traceback | 1.2.7 | Planned |
| P1 | wiki graph | 7.1.4 | Partially Implemented |
| P2 | fmlint | 7.5 | Implemented |
| P2 | json-lint | 7.11 | Implemented |
| P2 | mdoctor fix | 7.4 | Partially Implemented |
| P2 | Logging | 7.17 | Partially Implemented |
| P2 | Settings schema | 5 | Implemented |
| P2 | Sanity reporting, coverage, progress | 7.14 | Implemented |
| P2 | Shellcheck | 7.9 | Planned |
| P2 | Markdown code-block lint | 7.10 | Planned |
| P2 | html-js-lint | 7.15 | Planned |
| P2 | python-ruff fix subcommand | 7.8.2 | Planned |
| P2 | Wiki root discovery | 7.20 | Planned |
| P2 | settings setup | 7.16 | Planned |
| P2 | Bootstrap install modes | 7.21 | Implemented |
| P2 | wiki ingest | 7.1.5 | Partially Implemented |
| P2 | Ingest login detection and --origin |
7.1.5.2.8, 7.1.5.2.9, 7.1.5.14 | Implemented |
| P2 | HTML block sweep | 7.1.5.4.5.6 | Implemented |
| P2 | wiki search | 4.7.7, 7.1.6 | Planned |
| P2 | Staging in refine/ |
7.1.5.15 | Planned |
| P3 | --version |
2.3 | Planned |
| P3 | fmlint enforcement of quality signals | 6.2 | Planned |
| P3 | Backup archive | 7.13 | Planned |
| P3 | Documentation refresh | 7.18 | Partially Implemented |
| P2 | Graph skips gitignored files | 7.1.4.17 | Planned |
| P3 | Node importance filter | 7.1.4.16 | Planned |
| P2 | Graph directory nodes | 7.1.4.18 | Planned |
| P2 | Graph live view (--serve) |
7.1.4.19 | Planned |
| P2 | librarian move with link rewrite | 7.3.3 | Planned |
| P4 | Non-markdown version tags | 7.3.2 | Planned |
| P4 | Tool-role table | 7.19 | Planned |
Appendix C. Open Questions
- Python and shell version-tag format (section 7.3.2) is undecided. Do not build a scanner until this section names the format.
- Wiki root discovery when several
fiona-settings.jsonfiles exist under the start directory: the rule is not chosen. Candidates are "the nearest directory wins" and "error when two files sit at the same depth". Parent walk is already what graph settings do, and is a third candidate for the default directory. Section 7.20 stays planned until one rule is written here. - json-lint
chklintexits 1 when violations exist. mdoctor, fmlint, and python-ruff exit 0. A future change may align them. Until this line changes, implement the split in section 4. wiki ingesttakes one file or URL. A directory argument, and a barewiki ingestthat drainsingest/, are not specified.- More converters for section 7.1.5, each one class under 7.1.5.1.2.:
Office files (
mammothfor docx,python-pptx,openpyxl), ormarkitdownas one optional extra that covers them all but pulls inmagikaandonnxruntime. OCR for scanned PDFs is not chosen. PDF tables needpdfplumberor similar; pypdf reads text only. - Images and other assets referenced by an ingested source are not
copied into
raw/assets/. - Third-party converters could register through a package entry
point group such as
fiona.ingest_converters. Not decided. - The SHA-256 check in 7.1.5.3.3. scans
raw/on every run. A cached hash index is not specified until a largeraw/makes the scan slow. - A directory view (7.1.4.18.5.) draws outside nodes that its pages point at. Drawing outside nodes that point into the directory, as a second setting, is not decided.
--serve(7.1.4.19.5.) reloads the page on every rebuild. Patching the drawn graph in place, with no reload, is not specified. It needs the D3 joins keyed by node id.librarian move(7.3.3.4.4.) does not rewrite links in HTML tags (<a href>,<img src>). Whether it should is not decided.git undoandgit cleandiscard work with no prompt. The 2026-10-02 manual test lost agit savecommit this way. A TTY prompt with--yes(1.2.2.) would make agents pass--yeson every call. Not decided.wiki ingestsends no credentials (7.1.5.2.8.1.). A cookie file, a bearer token from an environment variable, or a--headeroption would let it read some login-only hosts itself. Each one puts secrets near the wiki. Not decided.- On exit 4,
--jsonprints nothing (7.1.5.13.). A JSON error object such as{"error": "auth_required", "url": ..., "reason": ...}would save the agent parsing stderr. Not decided. - The block sweep (7.1.5.4.5.6.3.) drops a block whose text has no
letter or digit, so an image or figure with no caption text is
not in the page. Counting
alttext, or keeping such a block asreview, is not decided. - Per-host URL rewrites before fetch (for example Reddit to
old.reddit.com), and pages that build their text with JavaScript, are not specified. - Moving a page from
refine/towiki/is a hand step for the agent (7.1.5.15.6.). Awiki promote <page>command could check the conditions of 7.1.5.10., move or merge the page, and append the log line. Not decided.
Appendix D. Maintainer Notes
These notes are not requirements. They point at the current tree.
| Area | Module |
|---|---|
| CLI dispatch | src/fiona/__main__.py |
| Logging | src/fiona/logging_config.py |
| template path | src/fiona/paths.py |
| librarian list | src/fiona/librarian/librarian.py |
| TOC | src/fiona/librarian/toc_generator.py |
| librarian move (planned) | src/fiona/librarian/mover.py, src/fiona/librarian/link_rewriter.py |
| mdoctor | src/fiona/mdoctor/mdoctor.py |
| fmlint, mdlinter, pycustomlint, json-lint | src/fiona/customlinter/ |
| ruff wrapper | src/fiona/python_ruff/python_ruff.py |
| wiki init | src/fiona/wiki/wiki.py |
| wiki gitignore | src/fiona/wiki/ignore.py |
| wiki update | src/fiona/wiki/update_manager.py |
| wiki sanity | src/fiona/wiki/sanity_manager.py |
| housekeeping | src/fiona/wiki/housekeeping.py |
| wiki graph | src/fiona/wiki/graph_generator.py, src/fiona/wiki/templates/graph_template.html, src/fiona/wiki/templates/graph_physics.js |
wiki graph --serve (planned) |
src/fiona/wiki/graph_server.py, src/fiona/wiki/templates/graph_live.js |
| git | src/fiona/gittool/git_tool.py |
| sanity engine | src/fiona/sanity_runner/sanity_runner.py |
| runners | src/fiona/run_tests.py, src/fiona/run_sanity.py |
| launchers | scripts/run_tests.py, scripts/run_sanity.py |
| bootstrap | bootstrap, bootstrap.ps1, scripts/bootstrap_install.py |
Layout for section 7.1.5, under src/fiona/wiki/ingest/:
| Module | Classes | Role |
|---|---|---|
models.py |
FetchedSource, ConversionResult, IngestResult, IngestError, AuthRequiredError |
Dataclasses passed between stages. IngestResult.to_dict() is the JSON in section 4.7.6. AuthRequiredError is exit 4. |
fetchers.py |
SourceFetcher (ABC), LocalFileFetcher, UrlFetcher |
accepts(argument) and fetch(argument, dest_dir). UrlFetcher takes the opener and runs the login checks of 7.1.5.2.8.2. before writing. |
settings.py |
IngestSettings, load_ingest_settings() |
fiona.wiki.ingest keys of section 5.1. |
media.py |
detect_media_type, make_slug |
7.1.5.2.4. and 7.1.5.2.6. |
converters/base.py |
SourceConverter (ABC), ConverterRegistry, ConversionError |
Class attributes name, media_types, extensions, raw_category; convert(source). ConverterRegistry.find(media_type, extension). |
converters/markdown.py, text.py, html.py, pdf.py |
MarkdownConverter, TextConverter, HtmlConverter, PdfConverter |
One format each. HtmlConverter(min_words, max_link_density); default_registry(settings) passes the html.* settings. |
converters/html_sweep.py |
Block, SweepResult, sweep() |
7.1.5.4.5.6. walk, classify, and render. |
archiver.py |
RawArchiver |
7.1.5.3.; find_by_sha256(digest, size) scans raw/ for a reusable copy. |
page_writer.py |
RawPageWriter |
7.1.5.5. |
log_writer.py |
IngestLog |
7.1.5.6. |
pipeline.py |
IngestPipeline, default_pipeline() |
Runs the stages; list_pending(wiki_root) is 7.1.5.9. |
Known defects to avoid copying blindly:
json-lint fixwalks the file list twice. The observable contract is one count and one path line per fixed file.- The previous spec's graph physics (
mass = 1 + in_degree * 0.5, center0.1,alphaMin0.1,velocityDecay0.6, and "D3 or vis.js") does not match the template. Section 7.1.4 is the contract. - The previous spec's external-link JSON used
{url, count}objects. The implementation emits unique URL strings plus a total count. - pymarkdown rule typos fail silently (section 5.1).
mdoctor fixdoes not skip read-only zones (section 4.2).