docs: document the system end-to-end (bootstrap/doctor/maintain/auto-sync)#45
Open
abdout wants to merge 2 commits into
Open
docs: document the system end-to-end (bootstrap/doctor/maintain/auto-sync)#45abdout wants to merge 2 commits into
abdout wants to merge 2 commits into
Conversation
Phase 4 polish. Two changes that make the docs feel current and discoverable without rewiring infrastructure. - Hover-anchor # next to every h2/h3/h4. Slugify helper extracted so ids are stable across renders and consistent across heading levels. Anchor is opacity-0 by default and fades in on group-hover or when the link itself receives focus (keyboard-accessible). - src/lib/docs.ts declares PAGES_NEW (4 entries, the Phase 3 resources) and PAGES_UPDATED (10 entries, the pages templated in Phase 2 and 3). - Sidebar renderLink now reads those arrays and shows a small inline badge (primary tint for New, muted for Updated). New beats Updated if both are flagged. Why: hover-anchors are the simplest way to give every section a permanent, copy-able URL. Badges surface what's worth re-reading without forcing users to scan the changelog. Deferred: mobile sidebar via Sheet — it needs the shadcn Sidebar component switched from collapsible="none" to "offcanvas" plus a layout-level SidebarTrigger, which risks regressing desktop behavior. Splitting into its own PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…uto-sync
Adds the operational engine documentation that was missing from the new
hierarchical IA. Five new pages plus a master overview tie together the
six scripts that run on every teammate's machine.
New pages:
reference/system.mdx master overview — the 6 scripts, the
cold-start flow, the steady-state loop,
the ~/.claude/ artifact map, the repo
layout, the friendly URLs, exit code
semantics, and known gaps
operations/bootstrap.mdx the 16-step single-paste cold start —
run command, full step table, flags,
OAuth batch, roles
operations/doctor.mdx 7 check categories, status icons,
exit codes, auto-fix slugs, sample
green report, known false positives
operations/maintain.mdx daily heartbeat — install per OS,
what each run does, log format,
relationship to auto-sync
operations/auto-sync.mdx real-time bidirectional git sync —
install, config flags, log format,
service backend per OS, troubleshooting
Updated:
reference/repositories.mdx adds 'Local layout' section near the
top — the canonical answer to 'where
does X live?' is now the first thing
a reader sees. Includes OS expansion
table and migration commands from the
old ~/oss/* layout.
operations/meta.json adds 'System' divider + bootstrap,
doctor, maintain, auto-sync to sidebar
reference/meta.json adds system as the first reference doc
Each page lives in the IA spot that matches the shadcn-style hierarchy
introduced earlier. Internal cross-links use the new paths.
Refs #28
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fills the gaps in the new hierarchical IA with five operational-engine docs that document everything we built over the bootstrap chain + repos-at-home + auto-sync work. One master overview ties them together.
Pages added
reference/system.mdx~/.claude/artifact map, repo layout, friendly URLs, exit code semantics, and known gapsoperations/bootstrap.mdxoperations/doctor.mdxoperations/maintain.mdxoperations/auto-sync.mdxPages updated
reference/repositories.mdxoperations/meta.json---System---divider + the 4 new pages to the sidebarreference/meta.jsonsystemas the first reference docWhy this PR exists
Three earlier PRs (#37 onboarding rewrite, #38 repos at home root, #41 auto-sync) shipped their docs at the top-level
content/docs/directory, which predated the shadcn-style hierarchical IA restructure in PR #39. This PR ports/extends that content into the new IA spots and adds the missing operational pages (bootstrap,doctor,maintain) that didn't exist anywhere before.Cross-linking
Every new page links to:
reference/system(the master overview).claude/scripts/*source file on GitHubdoctor↔maintain↔auto-sync)Dependencies
Stacks on
docs/shadcn-new-sections(the active docs branch) to inherit the new IA. No dependency on the bootstrap chain (#29-#36) — these are docs describing future-merged scripts. They'll be accurate once the script PRs land.Test plan
pnpm dev— navigate the new sidebar entries, confirm pages render without MDX errors/docs/reference/repositoriesshows "Local layout" as the first section after the intro/docs/reference/systemrenders the ASCII diagrams correctlyKnown gaps (called out in
system.mdx)The doc lists 4 real-but-small rough edges as future tracking items:
Repair-Profileis PowerShell-version-blind (only writes to current host's$PROFILE)Check-Shell.ps1~/.claude/binfalse positive (regex doesn't match unexpanded$env:USERPROFILE)maintain -Installmay need admin on some Windows configsRefs #28
🤖 Generated with Claude Code