fix(cli): resolve doc anchors against zensical.toml, not the deleted mkdocs.yml

The Zensical migration (#353) removed mkdocs.yml, but roost-cli's
doc_anchors_resolve test reads it to assert that every URL `roostctl
doctor` prints resolves to a page that is published in the site nav and
carries a heading matching the anchor. The test has panicked on the
missing file ever since, leaving main red for any Rust-touching PR.

Ports the nav parser from MkDocs' YAML list entries to Zensical's TOML
array of one-key tables, and repoints both the test and its near-miss
guard at zensical.toml.

The reason CI never noticed is the more important half: rust-build is
gated on the `rust` path filter, so a docs-only PR runs no Rust job and
ci-success goes green over a broken `cargo test`. A new narrow `docnav`
filter (zensical.toml + docs/**) now also triggers rust-build — only
that job, since widening `rust` itself would drag four heavy jobs onto
every docs typo. Same class as the .mise.toml dotfile miss already noted
in that filter block.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SgxiEBQTqgNjPswKqcs12d

Author: charliek

.github/workflows/ci.yml

@@ -27,6 +27,7 @@ jobs:
       ci: ${{ steps.filter.outputs.ci }}
       deb: ${{ steps.filter.outputs.deb }}
       macbundle: ${{ steps.filter.outputs.macbundle }}
+      docnav: ${{ steps.filter.outputs.docnav }}
     steps:
       - uses: actions/checkout@v6
         with:
@@ -80,6 +81,16 @@ jobs:
               - 'mac/scripts/bundle-lib.sh'
               - 'mac/scripts/bundle-iced.sh'
               - 'mac/Resources/Info-iced.plist.template'
+            # roost-cli's `doc_anchors_resolve` test reads the site nav and
+            # every page it links, so those files are inputs to a RUST test
+            # even though no Rust file changes when they move. Without this,
+            # a docs-only PR can delete or rename what the test reads and
+            # `rust-build` never runs to notice — which is exactly how the
+            # MkDocs -> Zensical migration left main red while CI was green.
+            # Same class as the `.mise.toml` dotfile miss noted above.
+            docnav:
+              - 'zensical.toml'
+              - 'docs/**'
             ci:
               - '.github/workflows/ci.yml'
             # Deliberately NOT `linux`: that filter folds in the *rustcore
@@ -192,7 +203,10 @@ jobs:
 
   rust-build:
     needs: changes
-    if: needs.changes.outputs.rust == 'true' || needs.changes.outputs.fixtures == 'true' || needs.changes.outputs.ci == 'true'
+    # `docnav` rides along here only — this is the job that runs `cargo
+    # test`, and widening `rust` itself would drag four other heavy jobs
+    # onto every docs typo.
+    if: needs.changes.outputs.rust == 'true' || needs.changes.outputs.fixtures == 'true' || needs.changes.outputs.ci == 'true' || needs.changes.outputs.docnav == 'true'
     strategy:
       fail-fast: false
       matrix:

crates/roost-cli/src/doctor.rs

@@ -65,7 +65,7 @@ macro_rules! docs_base {
 /// [`doc`], so the link doctor prints and the anchor the test verifies
 /// cannot drift apart.
 /// `page` + `anchor` are read only by `doc_anchors_resolve`, which
-/// resolves them against `docs/` and `mkdocs.yml`'s nav; `url` is what
+/// resolves them against `docs/` and `zensical.toml`'s nav; `url` is what
 /// production emits. Carrying all three on one row built by [`doc`] is
 /// what makes the printed link and the verified anchor impossible to
 /// drift apart — hence the struct-level allow.
@@ -6072,43 +6072,45 @@ mod tests {
         out
     }
 
-    /// Is `rel` an actual nav entry — `- Title: page.md` or `- page.md` —
-    /// rather than a substring of a comment or a longer path?
+    /// Is `rel` an actual nav entry — `{ "Title" = "page.md" }` — rather
+    /// than a substring of a comment or of a longer path? Zensical's nav
+    /// is a TOML array of one-key tables, so the entry is the quoted
+    /// value; matching the quotes is what keeps `cli.md` from passing on
+    /// `reference/cli.md`.
     fn nav_lists(nav: &str, rel: &str) -> bool {
+        let quoted = format!("\"{rel}\"");
         nav.lines().any(|line| {
             let line = line.split('#').next().unwrap_or_default();
-            let Some(entry) = line.trim().strip_prefix("- ") else {
-                return false;
-            };
-            let value = entry.rsplit_once(": ").map_or(entry, |(_, v)| v);
-            value.trim() == rel
+            line.split('=')
+                .skip(1)
+                .any(|value| value.trim().trim_end_matches([',', '}', ']', ' ']) == quoted)
         })
     }
 
-    /// mkdocs' `nav:` block, bounded at the next top-level key — `extra:`
-    /// follows it today, and its entries are not nav entries.
-    fn nav_block(mkdocs: &str) -> String {
-        mkdocs
-            .split("\nnav:")
+    /// Zensical's `nav = [` array, bounded at the line that closes it.
+    /// `mkdocs.yml`'s `nav:` block was the pre-Zensical equivalent.
+    fn nav_block(zensical: &str) -> String {
+        zensical
+            .split("\nnav = [")
             .nth(1)
-            .expect("mkdocs.yml has a nav:")
+            .expect("zensical.toml has a nav = [")
             .lines()
-            .take_while(|l| l.trim().is_empty() || l.starts_with([' ', '\t']))
+            .take_while(|l| !l.starts_with(']'))
             .collect::<Vec<_>>()
             .join("\n")
     }
 
     /// Deliberately one-directional: for each `(page, anchor)` doctor can
-    /// emit, assert the page exists, that it is in `mkdocs.yml`'s
+    /// emit, assert the page exists, that it is in `zensical.toml`'s
     /// hand-maintained nav (`docs/reference/terminal-queries.md` is the
     /// counterexample on disk today), and that some heading slugifies to
-    /// the anchor. It does NOT reimplement mkdocs' slugify over every
+    /// the anchor. It does NOT reimplement the site generator's slugify over every
     /// heading in the repo — only these URLs matter.
     #[test]
     fn doc_anchors_resolve() {
         let root = repo_root();
-        let mkdocs = std::fs::read_to_string(root.join("mkdocs.yml")).expect("mkdocs.yml");
-        let nav = nav_block(&mkdocs);
+        let zensical = std::fs::read_to_string(root.join("zensical.toml")).expect("zensical.toml");
+        let nav = nav_block(&zensical);
 
         let mut targets: Vec<Doc> = DOC_TARGETS.iter().map(|(_, d)| *d).collect();
         targets.push(EXIT_CODES_DOC);
@@ -6125,7 +6127,7 @@ mod tests {
                 .unwrap_or_else(|e| panic!("{}: {e}", path.display()));
             assert!(
                 nav_lists(&nav, &rel),
-                "{rel} is not in mkdocs.yml's nav, so its URL would not publish"
+                "{rel} is not in zensical.toml's nav, so its URL would not publish"
             );
             let found = headings(&body)
                 .into_iter()
@@ -6145,7 +6147,7 @@ mod tests {
         let body = "# Real\n\n```bash\n# 1. Allow it as a login shell\n```\n\n## Also Real\n";
         assert_eq!(headings(body), vec![" Real", " Also Real"]);
 
-        let nav = "  - CLI: reference/cli.md\n  # - Queries: reference/terminal-queries.md\n";
+        let nav = "  { \"CLI\" = \"reference/cli.md\" },\n  # { \"Queries\" = \"reference/terminal-queries.md\" },\n";
         assert!(nav_lists(nav, "reference/cli.md"));
         assert!(
             !nav_lists(nav, "reference/terminal-queries.md"),
@@ -6156,7 +6158,7 @@ mod tests {
             "a suffix of a nav path is not a nav entry"
         );
         assert!(!nav_lists(
-            &nav_block(&std::fs::read_to_string(repo_root().join("mkdocs.yml")).unwrap()),
+            &nav_block(&std::fs::read_to_string(repo_root().join("zensical.toml")).unwrap()),
             "reference/terminal-queries.md"
         ));
     }