docs(mcpx): stand up the mdBook book and .#mcpx-docs flake output (#1939) by dezren39 · Pull Request #2629 · developing-today/code

dezren39 · 2026-10-30T08:15:40Z

Implements the #1939 decision (Approach C) — queue task 3236.

pkgs/mcpx/book.toml — mdBook config; book root is pkgs/mcpx, src = "docs", create-missing = false.
pkgs/mcpx/docs/SUMMARY.md — covers all 101 existing docs pages (titles taken from each page's first heading); no existing docs content rewritten or dropped.
pkgs/mcpx/docs.nix — sandboxed runCommand rendering the book with the flake-pinned mdbook from nixpkgs (fileset source: only book.toml + docs/), no network.
lib/default.nix — wires it as packages.mcpx-docs in make-root-apps, so nix build .#mcpx-docs and the CI flake-check path cover it.

Verified on the laptop before pushing: nix build .#mcpx-docs succeeds and produces the rendered book (index, configuration.html, story.html, subdirectories). Existing mcpx Go checks, including internal/settings/docs_test.go, are untouched and run in CI.

Out of scope per the packet: hand-written home page, llms.txt/.md twin emitter, version-history preprocessor, deployment/Pages wiring (sibling issues).

Closes #1939 on merge.

^{Need help on this PR? Tag @codesmith-bot with what you need.}

) Approach C from #1939: pkgs/mcpx/book.toml (src = docs, create-missing off), docs/SUMMARY.md covering all 101 existing docs pages without rewriting any content, and pkgs/mcpx/docs.nix rendering the book with the flake-pinned mdbook in a sandboxed runCommand. Wired as packages.mcpx-docs in make-root-apps so nix build .#mcpx-docs (verified locally on the laptop) and the CI flake-check path cover it.

chatgpt-codex-connector · 2026-10-30T08:15:47Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T11:32:19.108099Z	`4de2f18`	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

coderabbitai · 2026-10-30T08:15:48Z

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 37 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 872688a3-2f82-4fe0-8edb-6f848a1b9cf9

Commits

Reviewing files that changed from the base of the PR and between 7b76c79 and 9ca8f80.

Files selected for processing: 5

lib/default.nix
pkgs/mcpx/book.toml
pkgs/mcpx/docs.nix
pkgs/mcpx/docs/SUMMARY.md
pkgs/mcpx/docs/compendium.manifest.json

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7530992a2b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-10-30T08:18:14Z

+    fileset = lib.fileset.unions [
+      ./book.toml
+      ./docs
+    ];


Preserve links to resources outside the book source tree

When readers use the rendered book, links to files outside docs/ lead outside the generated artifact instead of to their existing repository targets. For example, quick-start.md:49 directs readers to ../AGENTS.md to configure their agent, while story.md links to ../daemon/README.md and maintenance scripts. Repository-tree inspection confirms those targets exist, but this fileset excludes them and the build provides no link rewriting or corresponding output files. Rewrite these links to repository URLs or explicitly include and publish the referenced resources so the book's onboarding and operational instructions remain usable.

Useful? React with 👍 / 👎.

Fixed in 684a133 (pushed to this PR).

The build in pkgs/mcpx/docs.nix now rewrites links that escape the book source tree — in the copied pages only — to the target file's repository URL, at the depth where each link escapes: ../ from a top-level page and ../../ from a page one directory down both resolve to pkgs/mcpx/<target>, i.e. https://github.com/developing-today/code/blob/main/pkgs/mcpx/<target>. The sources keep their relative links (which keep working on GitHub), and links that stay inside docs/ are left for mdBook to resolve.

Verified locally at the pushed head: nix build .#mcpx-docs succeeds; the rendered story.html carries 9 rewritten links (including ../AGENTS.md), compare/history.html carries 6, no href="../AGENTS.md" remains, and in-book links such as ../story.html are untouched.

TestEveryDocumentHasAChapter requires every markdown file to be placed. SUMMARY.md is the mdBook navigation index the generator reads, not a chapter, so it lands as not-compendium with chapter null.

…x-docs build (#1939) Dispositions the Codex P2 finding on PR #2629: rendered-book links to files outside docs/ (../AGENTS.md, ../daemon/README.md, ../../ASSESSMENT.md, maintenance scripts) led outside the generated artifact and 404ed. The build now rewrites escaping links in the copied pages only - at the depth where each escapes (../ from top-level pages, ../../ from pages one directory down) - to the target file's GitHub URL. Sources keep their relative links, which keep working on GitHub; links that stay inside docs/ are left for mdBook to resolve. Verified on the laptop: nix build .#mcpx-docs succeeds; story.html carries 9 rewritten links and compare/history.html 6, no href="../AGENTS.md" remains, and in-book links (../story.html) are untouched.

dezren39 · 2026-10-30T10:27:06Z

🤖 Agent note · duplicate reconciled (queue task 3236)

Agent: queue worker (repo-worker-code), lane E shift
A later claim of this same task produced a second implementation, PR docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680 (branch queue/3236-1939-mdbook), before its author saw this PR. Per the queue protocol §8, this PR is canonical (earlier, same task) and docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680 is being closed as the duplicate.
Salvage check (diffed, not file-list only): nothing unique to port. docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680 differed only in layout choices that are strictly less complete here: book.toml inside docs/ with src = "." instead of this PR's book root at pkgs/mcpx with src = "docs" + create-missing = false; a plain cp -r of the docs tree instead of this PR's fileset-scoped source; no rewriting of links that escape the book tree (this PR handles them); SUMMARY.md generated from first headings with Decisions/Specification groupings vs this PR's summary — same 62-file coverage, presentation only.
The nix build evaluation failure recorded on docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680 (callPackage arguments in the make-root-apps scope) was observed against docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680's worktree only; this PR's identical callPackage pattern should be verified by its own build/CI rather than assumed broken.

dezren39 · 2026-10-30T10:27:44Z

🤖 Agent note · correction to the salvage note above

The nix build .#mcpx-docs evaluation failure I recorded against (now-closed) docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680 did not reproduce: the completed build run for that identical callPackage pattern finished successfully and produced the book (/nix/store/2klxi61bjnvz3nr6c0cnajj6ji727nrq-mcpx-docs on the laptop). The two earlier failures (missing lib, then mdbook arguments) were transient evaluation flakes, not a defect in this pattern.
So: no phantom bug to diagnose here. Resume path for task 3236 is simply this PR's own build/CI verification, then merge under the standing criteria.

…mdbook # Conflicts: # pkgs/mcpx/docs/compendium.manifest.json

…ium manifest (#1939)

dezren39 requested a review from a team as a code owner October 30, 2026 08:15

dezren39 mentioned this pull request Oct 30, 2026

mcpx docs: choose the site generator (mdBook, MkDocs Material, Docusaurus, Starlight, Hugo) #1939

Closed

chatgpt-codex-connector Bot reviewed Oct 30, 2026

View reviewed changes

dezren39 mentioned this pull request Oct 30, 2026

mcpx docs: build the site in CI and deploy to GitHub Pages #1941

Closed

dezren39 added 2 commits October 30, 2026 03:46

docs(mcpx): register SUMMARY.md in the compendium manifest (#1939)

49fe420

TestEveryDocumentHasAChapter requires every markdown file to be placed. SUMMARY.md is the mdBook navigation index the generator reads, not a chapter, so it lands as not-compendium with chapter null.

dezren39 mentioned this pull request Oct 30, 2026

docs(mcpx): mdBook skeleton + .#mcpx-docs flake output (#1939) #2680

Closed

ci: retrigger workflows on current head (#1939)

43f24bd

dezren39 mentioned this pull request Oct 30, 2026

CI: pushes to PR #2629 after opening created no workflow runs (synchronize events dropped) #2713

Closed

Merge remote-tracking branch 'origin/main' into queue/3236-1939-mcpx-…

4de2f18

…mdbook # Conflicts: # pkgs/mcpx/docs/compendium.manifest.json

github-actions Bot assigned dezren39 Oct 30, 2026

docs(mcpx): register docs/testing/feature-inventory.md in the compend…

9ca8f80

…ium manifest (#1939)

dezren39 merged commit c8ee2a6 into main Oct 30, 2026
5 checks passed

dezren39 deleted the queue/3236-1939-mcpx-mdbook branch October 30, 2026 11:33

dezren39 mentioned this pull request Oct 30, 2026

ci(mcpx): build docs in CI and deploy to GitHub Pages (#1941) #2721

Merged

Navigation Menu

Repository navigation

docs(mcpx): stand up the mdBook book and .#mcpx-docs flake output (#1939) - #2629

docs(mcpx): stand up the mdBook book and .#mcpx-docs flake output (#1939)#2629
dezren39 merged 6 commits into
mainfrom
queue/3236-1939-mcpx-mdbook

dezren39 commented Oct 30, 2026 •

edited by blacksmith-sh Bot

Loading

Uh oh!

chatgpt-codex-connector Bot commented Oct 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 30, 2026 •

edited

Loading

Review limit reached

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Oct 30, 2026

Uh oh!

dezren39 Oct 30, 2026

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

dezren39 commented Oct 30, 2026 • edited by blacksmith-sh Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

coderabbitai Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

dezren39 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

dezren39 commented Oct 30, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dezren39 commented Oct 30, 2026 •

edited by blacksmith-sh Bot

Loading

chatgpt-codex-connector Bot commented Oct 30, 2026 •

edited

Loading

coderabbitai Bot commented Oct 30, 2026 •

edited

Loading