96 KiB
name, version, title, created, updated, type
| name | version | title | created | updated | type |
|---|---|---|---|---|---|
| Fiona-Assistant Specification | 0.90.1 | Project Spec Sheet | 2026-09-23 | 2026-09-30 | 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 init
- 7.2. wiki update
- 7.3. wiki sanity
- 7.4. wiki graph
- 7.5. Git Operations
- 7.6. Backup Script
- 7.7. mdoctor
- 7.8. fmlint
- 7.9. mdlinter
- 7.10. pycustomlint
- 7.11. python-ruff
- 7.12. Shellcheck
- 7.13. Markdown Code Blocks
- 7.14. Non-markdown Version Tags
- 7.15. Folder and In-file TOC
- 7.16. Test and Sanity Runners
- 7.17. html-js-lint
- 7.18. json-lint
- 7.19. settings setup
- 7.20. Logging
- 7.21. Documentation
- 7.22. Tool Roles
- 7.23. Wiki Root Discovery
- 7.24. Bootstrap install modes
- 8. Non-Goals
- 9. Priority Order
- 10. Open Questions
- Appendix A. 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.
Revision 0.40.0 reorganizes the sheet into contracts. Revision 0.40.1
numbers nested requirements such as 7.16.1.1. Revision 0.40.4 adds
the PYC001 exception in 6.4.2.. Revision 0.41.0 installs one
fiona package and keeps tests and repo scripts outside it.
Revision 0.90.0 specifies node_importance_min_point in 7.4.16.
and leaves that requirement unbuilt.
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 A.
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.16.1.*then*7.16.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.16 are
numbered
7.16.1and7.16.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.- acceptance:
wiki updateleaves every file underpersonal/andraw/byte-for-byte unchanged.
- 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.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
2. Package and Runtime
Status: 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.24 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.17
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.17 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.17 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
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
README.md
fiona-settings.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/obsidian/SKILL.md
utils/skills/python-tdd/SKILL.md
utils/personas/default/SOUL.md
utils/personas/template/SOUL.md
utils/skills_local/README.md
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/
Read-only zones, including the zone directory itself:
personal/raw/
wiki update adds missing core files and directories. 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.
After the copy, wiki init creates a git repository, writes
.gitignore containing a comment line and personal/, stages
everything, and commits Initial llm-wiki commit. 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
4. Command Catalog
Status: Implemented
One command tree. Optional [directory] defaults to . today.
Wiki-root discovery (section 7.23) 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.2. 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.15. --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.3. 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/.
4.4. 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.5. 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.6. 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.7. 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.8. wiki init
fiona-assistant wiki init [directory]. Success stdout:
Successfully initialized llm-wiki directory at: <resolved path>
Rules are section 3.
4.9. 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>)
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.
--json prints one JSON object:
{
"files_to_update": [
{
"path": "<path>",
"current_version": "<version or null>",
"template_version": "<version or null>",
"is_settings_file": false
}
],
"files_to_add": [],
"directories_to_add": [],
"files_skipped": [
{"path": "<path>", "reason": "locally modified"}
],
"total": 0,
"has_updates": false
}
4.10. 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, <S> skipped.
--json suppresses the plan and prints:
{
"files_updated": [],
"files_added": [],
"directories_added": [],
"files_skipped": [],
"total": 0
}
Comparison and merge rules are section 7.2.
4.11. 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.16.
4.12. 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].
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.4.
4.13. 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.16.
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
}
}
}
}
| 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.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.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.node_importance_min_point |
int >= 0 |
0 | wiki graph |
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.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.4.16.
and is not built yet. The packaged fiona-settings.json omits
the key until that requirement is built. Absent means 0.
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, fiona-settings.json is deep-merged. 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.
- 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. A user value nested under
markdownsurviveswiki updatewhen the template also has that key, and a brand-new template key appears in the merged file.- acceptance:
markdown.pymarkdown.md013.line_lengthset to 120 is still 120 after update, and a new template key is present.
- 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-settings.json
Themes for the wiki graph. The file has a themes object. colorful
is complete. 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.
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 silver to white. 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 |
buttons.background/text/hover/disabled |
Button colors |
card.background/border |
Cards, legend, and the control bar |
shapes.page |
circle, cloud, or star |
shapes.external |
Shape for an external-link node |
subtitle_color |
Label under a large node |
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,
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. |
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 13 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 |
- 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.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 init
Status: Implemented
Implements sections 3 and 4.8.
- 7.1.1. Copy is 1:1 aside from
DATE_PLACEHOLDERandignore_files.- acceptance: A pattern in
ignore_filesomits those paths and copies every other template file.
- acceptance: A pattern in
- 7.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.2. wiki update
Status: Implemented
Implements sections 4.9 and 4.10.
- 7.2.1. Markdown core files are compared as follows.
- 7.2.1.1. Both sides have
version, and the template version is greater: update. Numeric dotted versions compare segment by segment (1.2.0vs1.10.0). Any other string compares as text. - 7.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.2.1.3. Either version is missing: update when the expanded text differs. Binary files compare SHA-256.
- 7.2.1.1. Both sides have
- 7.2.2. Other core files compare SHA-256 and update when the hash differs.
- 7.2.3.
fiona-settings.jsonuses the hash comparison to decide that an update is needed, then writes the deep merge from section 5.1. - 7.2.4. Missing template directories are created. User files that are not in the template stay. Read-only zones are never in the update set.
- 7.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.2.6. An older core markdown file is listed and, after a
confirmed update, 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: The modified file's bytes are unchanged after
- 7.2.7.
--dry-runprints the plan and leaves the tree unchanged.- acceptance: File hashes before and after a dry run match.
- 7.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.3. wiki sanity
Status: Implemented
Implements section 4.11. 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.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.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.3.3. Human output uses the progress display in 7.16.2.
with label
Running Wiki Sanity.- acceptance: A piped run prints that label and dots, and no ANSI escapes.
7.4. wiki graph
Status: Partially Implemented
7.4.16. is 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.4.1. The parser extracts links as follows.
- 7.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.4.1.2. Wikilinks
[[file]]and[[dir/file]]are parsed when wikilinks are enabled. - 7.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.4.1.4. A link whose target file is missing is recorded as broken and does not abort the run.
- 7.4.1.1. Markdown links
- 7.4.2. The graph is built as follows.
- 7.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.4.2.2. An orphan has in-degree 0 and out-degree 0.
- 7.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.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.4.4. When external URLs were collected,
metadataalso hasexternal_links_count(total occurrences) andexternal_links(unique URL strings). - 7.4.5. HTML behavior.
- 7.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.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.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.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.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.4.5.6. Double click opens the markdown file.
- 7.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.4.5.8. A checkbox toggle labeled "Show Orphan Nodes" shows or hides orphans. It starts checked. The label does not change.
- 7.4.5.9. Overwrite of an existing output file asks for confirmation on a TTY.
- 7.4.5.10. Files above
max_filesare skipped after a warning. The firstmax_filesfiles are drawn. - 7.4.5.11. The run completes in under 10 seconds for 1000 files on a current developer machine.
- 7.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.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.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.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.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.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.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.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.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.4.5.1. One self-contained file. The layout fills the
viewport and follows resize. The page script is
- 7.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.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.4.8. The output path must be writable. A failure is an error message and a non-zero exit.
- 7.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.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.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.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.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.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.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.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.4.16.1.
NOT_IMPLEMENTEDThe count isunique_pointsfrom 7.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.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.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.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.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.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.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.4.16.1.
7.5. Git Operations
Status: Implemented
Implements section 4.7. personal/ is listed in .gitignore at
wiki init and is never staged by these commands except where
git add --all respects that ignore file.
- 7.5.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.5.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.5.3.
undoandrestoreon a dirty tree exit 1 and mentionclean.- acceptance: The HEAD sha is unchanged.
- 7.5.4.
cleanleavesgit statusempty of changes.- acceptance: A following
statusprintsStatus: clean.
- acceptance: A following
7.6. Backup Script
Status: Planned
- 7.6.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.6.2.
NOT_IMPLEMENTEDThe archive is stored outside the wiki tree.- acceptance: The archive path is not under the wiki root.
- 7.6.3.
NOT_IMPLEMENTEDThe filename isYYYYMMDD_hhmm_<description>.zstd.- acceptance: The file is valid zstd and the name matches.
- 7.6.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.7. mdoctor
Status: Implemented
Implements section 4.3 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.7.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.7.2. A tree with nothing to fix prints
PyMarkdownFix: 0 file(s) fixed.- acceptance: That line is the only stdout line.
- 7.7.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.8. fmlint
Status: Implemented
Implements sections 4.4 and 6.2.
- 7.8.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.8.2.
enabled: falsereports no frontmatter violations.- acceptance: A file with no frontmatter is clean for fmlint.
- 7.8.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.9. 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.9.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.10. pycustomlint
Status: Implemented
Implements section 6.4. The sanity runner in section 7.16 includes
it as pycustomlint. There is no fiona-assistant pycustomlint
command; the repository runner calls the library.
- 7.10.1.
--jsonprints a JSON list of violation objects.- acceptance:
json.loadssucceeds and each object hascode.
- acceptance:
7.11. python-ruff
Status: Implemented
Implements section 4.5. The sanity check name is ruff in
run_sanity.py and python-ruff in wiki sanity.
- 7.11.1. An unused import appears in DEFINITIONS, FILE, and
SUMMARY.
- acceptance: The FILE line contains the ruff rule code.
- 7.11.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.12. Shellcheck
Status: Planned
- 7.12.1.
NOT_IMPLEMENTEDWrap theshellcheckbinary and print the shared report.- acceptance: A known shellcheck finding shows file, line, and rule code.
- 7.12.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.12.3.
NOT_IMPLEMENTEDWiki sanity runs this check.- acceptance: The
Results:table includes the new check name.
- acceptance: The
7.13. Markdown Code Blocks
Status: Planned
- 7.13.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.13.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.13.3.
NOT_IMPLEMENTEDWiki sanity runs this check.- acceptance: The check appears in the
Results:table.
- acceptance: The check appears in the
7.14. Non-markdown Version Tags
Status: Planned
- 7.14.1.
NOT_IMPLEMENTEDPython and shell files gain a version tag. The tag format is undecided (section 10). Do not implement until that format is chosen.- acceptance: The format is written in this spec before any scanner ships.
7.15. Folder and In-file TOC
Status: Implemented
- 7.15.1. Folder TOC (
librarian toc).- 7.15.1.1.
table_of_contents.mdhas frontmattertitle,created,updated, andtype: toc. - 7.15.1.2. Entries list subfolders, file links, and
v<version>, orv0.0.0when version is missing or unreadable. - 7.15.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. - 7.15.1.4. Skip the TOC file itself, hidden folders, and
--excludematches. - 7.15.1.5.
--recursive-tocwrites a TOC in every subfolder. - 7.15.1.6.
--non-recursivelists only markdown files directly in the folder, ignoringmax_depth_from_dir. - 7.15.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.15.1.1.
- 7.15.2. In-file TOC (
librarian toc file).-
7.15.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.15.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.15.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.15.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.15.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.15.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.15.2.7.
toc file *skips read-only zones, hidden files and folders,table_of_contents.md, andignore_filesmatches. -
7.15.2.8.
toc file <explicit path>insidepersonal/orraw/, or a missing or non-markdown path, exits 1 and writes nothing.
-
- 7.15.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.15.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.15.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.15.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.15.7.
min_heading: 3omits##.max_heading: 3omits####.- acceptance: Each setting hides only its out-of-range level.
- 7.15.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.16. Test and Sanity Runners
Status: Implemented
- 7.16.1. Shared engine, used by
run_sanity.pyand wiki sanity.- 7.16.1.1. One thread per check. Results stay in registry order.
- 7.16.1.2. Summary line
PASS/FAIL - <detail> (MM:SS). Minutes may exceed 59 and are zero-padded. A missing duration omits the suffix. - 7.16.1.3.
SANITY PASSED (MM:SS)lists check names in registry order.Sanity Failed - N checks need attention:has no total time. - 7.16.1.4. A runner may add an extra result row, such as coverage, and per-check failure details.
- 7.16.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.16.2. Progress display.
- 7.16.2.1. On a TTY, one bar per check, redrawn in place with
cursor-up and line clear. Example:
pytests [###------------] 22% 6.5s. - 7.16.2.2. The bar fills as elapsed /
expected-seconds, capped at 100%. - 7.16.2.3. A finished check shows a full bar and
(MM:SS):markdownlint [###############] 100% done (00:07). - 7.16.2.4. The final block stays on screen above the reports.
- 7.16.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.16.2.6.
--jsonon wiki sanity skips the display. - 7.16.2.7. Bar scale and dot interval come from section 5.2.
- 7.16.2.1. On a TTY, one bar per check, redrawn in place with
cursor-up and line clear. Example:
- 7.16.3.
run_tests.pyand the pytests check.- 7.16.3.1. The command includes
--color=noand JUnit XMLjunit_family=xunit1. - 7.16.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.16.3.3. A missing short summary logs a WARNING that names
PYTEST_ADDOPTS,--no-summary, and plugin output as likely causes. - 7.16.3.4.
LOG_LEVEL=DEBUGlogs the pytest command, return code, parsed failures, and raw output when the parse disagrees. - 7.16.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.16.3.6. The
Sanity Failedverdict lists failing test names only. Assert text stays in the report body. - 7.16.3.7. The
coverage:line isPASS/FAIL - <percent>% (required <percent>%)and is untimed. A shortfall is its own verdict entry.
- 7.16.3.1. The command includes
- 7.16.4.
run_sanity.pycheck order ispytests,markdownlint,ruff,frontmatter_lint,pycustomlint,jsonlint. - 7.16.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.16.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.16.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.17. 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.17.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.17.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.17.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.17.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.17.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.17.6.
NOT_IMPLEMENTEDBothrun_sanity.pyand wiki sanity run this check.- acceptance: A violation fails that sanity run.
7.18. json-lint
Status: Implemented
Implements sections 4.6 and 6.5. Both sanity runners include it.
- 7.18.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.18.2. An empty tree of JSON files prints no violations.
- acceptance: The report says no violations were found.
7.19. settings setup
Status: Planned
fiona-assistant init remains the non-interactive wiki bootstrap
(section 7.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.19.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.19.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.19.3.
NOT_IMPLEMENTED--yesor--defaultapplies defaults with no prompts.- acceptance: The command exits 0 on a pipe when the flag is set.
- 7.19.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.19.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.20. Logging
Status: 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.20.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.20.2. Dropping
file_log_locationleaves no file handler.- acceptance: No log file is created for that run.
7.21. 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.21.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.21.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.21.3. Documentation markdown passes
mdoctor chklint.- acceptance:
README.mdcontains a markdown link toSPEC.mdand the lint report is clean.
- acceptance:
7.22. Tool Roles
Status: Planned
- 7.22.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.22.2.
NOT_IMPLEMENTEDMissing ingestion and processing steps become scripts under the templateutils/directory, such asingest.pyandprocess.py.- acceptance: Each new script is named in the role table.
7.23. Wiki Root Discovery
Status: Planned
Today every optional directory defaults to .. toc file * already
searches for fiona-settings.json as specified in section 7.15.
Graph settings already walk parent directories. The dispatcher does
not.
- 7.23.1.
NOT_IMPLEMENTEDWhen the directory argument is omitted, commands use the wiki root from section 10's discovery rule.- acceptance:
fiona-assistant mdoctorfrom a subdirectory lints that root, not the subdirectory.
- acceptance:
- 7.23.2.
NOT_IMPLEMENTEDAn explicit directory always wins.- acceptance:
mdoctor chklint sub/dirlintssub/direven when a settings file exists higher up.
- acceptance:
- 7.23.3.
NOT_IMPLEMENTEDWith no settings file found, the default stays..- acceptance: Behavior matches today's commands.
- 7.23.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.24. 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.24.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.24.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.24.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.24.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.24.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.24.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
8. Non-Goals
- 8.1. No LLM or network API inside Fiona-Assistant. The tools are deterministic.
- 8.2. No automated edit of
personal/orraw/content. - 8.3. No cloud sync and no remote backup. Version control is local. The planned archive in 7.6. is a local file.
- 8.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 the one
exception: the browser loads D3 from
d3js.org(7.4.). The generator itself does not call that host.
- acceptance: With the network unavailable,
9. Priority Order
| Priority | Feature | Section | Status |
|---|---|---|---|
| P1 | wiki update / check-update | 7.2 | Implemented |
| P1 | Git save, snapshot, restore, clean, undo, status | 7.5 | Implemented |
| P1 | wiki sanity, including dead links | 7.3 | Implemented |
| P1 | wiki graph | 7.4 | Partially Implemented |
| P2 | fmlint | 7.8 | Implemented |
| P2 | json-lint | 7.18 | Implemented |
| P2 | mdoctor fix | 7.7 | Implemented |
| P2 | Settings schema | 5 | Implemented |
| P2 | Sanity reporting, coverage, progress | 7.16 | Implemented |
| P2 | Shellcheck | 7.12 | Planned |
| P2 | Markdown code-block lint | 7.13 | Planned |
| P2 | html-js-lint | 7.17 | Planned |
| P2 | python-ruff fix subcommand | 7.11.2 | Planned |
| P2 | Wiki root discovery | 7.23 | Planned |
| P2 | settings setup | 7.19 | Planned |
| P2 | Bootstrap install modes | 7.24 | Implemented |
| P3 | fmlint enforcement of quality signals | 6.2 | Planned |
| P3 | Backup archive | 7.6 | Planned |
| P3 | Documentation refresh | 7.21 | Partially Implemented |
| P3 | Node importance filter | 7.4.16 | Planned |
| P4 | Non-markdown version tags | 7.14 | Planned |
| P4 | Tool-role table | 7.22 | Planned |
10. Open Questions
- Python and shell version-tag format (section 7.14) 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.23 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.
Appendix A. 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 |
| 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 update | src/fiona/wiki/update_manager.py |
| wiki sanity | src/fiona/wiki/sanity_manager.py |
| wiki graph | src/fiona/wiki/graph_generator.py, src/fiona/wiki/templates/graph_template.html, src/fiona/wiki/templates/graph_physics.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 |
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.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.3).