Migration/step 07

[surchs]

Title: chore(migration): step 07 docs
Branch: migration/step-07

Merge with a merge commit, not squash. This PR imports history.

Before or right after merging: in the repository settings under Pages, set Source to GitHub Actions. The deploy job cannot publish otherwise.

Summary

• Import: documentation imported with full history into docs/ (upstream eaa7411, rewritten head ae3cc86, no tags). The mkdocs project is at docs/mkdocs.yml with content in docs/docs/.
• .github/: docs/.github/ deleted. Its pre-commit checks are ported in Step 8; handle_external_pr, add_iss2project and stale are not carried over (Step 7d).
• .github/workflows/docs.yml:
  • On PRs touching docs/** or the workflow, it runs pip install -r requirements.txt && mkdocs build --strict on Python 3.10, as upstream CD did.
  • On push to main touching the same paths, or on workflow_dispatch, it builds and deploys with actions/upload-pages-artifact@v5 and actions/deploy-pages@v5, replacing mkdocs gh-deploy.
  • docs/docs/CNAME is kept.
• Docs: docs/README.md changes:
  • New section "Development in the Neurobagel monorepo".
  • The old-repository Actions badge is replaced by a docs-workflow badge.
  • "Deploy" now describes the automatic deployment.
  • The pre-commit install instruction is removed. In the monorepo, pre-commit only reads a root config until Step 8, so an installed hook would fail every commit.
  • Root README: a Step 7 row.

Checks run

Check	Result
scripts/check-unchanged.sh	OK for every entry, including docs docs
git rev-list --count <rewritten-head>	261 (upstream 261)
cd docs && pip install -r requirements.txt && mkdocs build --strict	OK, no warnings (baseline: OK, 0 warnings)
docs' own pre-commit hooks on docs/README.md (markdownlint with docs/.markdownlint.jsonc, codespell, whitespace)	pass
api / federation-api / bagel-cli tests	188 / 111 / 215 passed
query-tool and annotation-tool static checks; annotation-tool unit tests	pass; 240 passed
just lint	passes
After merge, the sandbox Pages URL serves the docs home page	to be confirmed (needs Pages source = GitHub Actions)
A PR touching only tools/api does not run the docs workflow	to be confirmed on GitHub (path filter docs/**)

Documentation check: the commands in the new README section were run verbatim in bash from docs/ in a fresh clone of this branch: python -m venv venv, source venv/bin/activate, pip install -r requirements.txt and mkdocs build --strict (OK). Two local substitutions were needed:

• The container has no python command and its system Python lacks venv, so python pointed to a uv-provided Python 3.10, the version CI uses.
• The git clone URL was replaced by a local clone of this branch.

Deviations from the plan

• Custom domain: with deploy-pages, GitHub ignores docs/docs/CNAME. The custom domain is set in the repository's Pages settings at cutover (Step 16 item 5); the sandbox ignores it, as planned.
• markdownlint config: run from the repository root, markdownlint did not find docs/.markdownlint.jsonc and reported default-rule errors (80-character lines). Step 8's root hook must pass -c docs/.markdownlint.jsonc (plan updated). With the docs config, only two duplicate headings in my new section were flagged; they were renamed.

🤖 Generated with Claude Code