docs: shll.ai README-extraction conformance by sahil-noon · Pull Request #22 · sahil87/wt

sahil-noon · 2026-06-08T10:10:05Z

Summary

Conforms this repo to shll.ai's README-extraction contract. shll.ai renders the wt tool page (slug wt, URL space /tools/wt/) by mechanically pulling a slice of README.md plus the docs/site/** tree on a daily schedule — nothing is hand-copied and nothing is pushed. The README had one site-fatal defect (a relative docs/specs/ link that renders as a live 404 on the site) plus a trailing orphan footer; this PR fixes both and adds the contract's encouraged docs/site/ depth tree. Nothing in shll.ai is touched — it pulls automatically.

Per-tool table row (from the contract): slug wt, binary wt, URL space /tools/wt/; reserved page names overview/readme/commands (avoided); install/workflows owned by this repo.

Changes

Part 1 — README.md restructure

Rewrite the line-77 relative docs/specs/cli-surface.md link into a natural docs/site/workflows.md link. docs/specs/ is never pulled and the slice is not closure-linted or rewritten, so the old link rendered as a live 404 on the site with no warning (contract §9.1.2 / directive rule 5).
Remove the trailing --- + repeated toolkit-footer blockquote so the pulled slice ends on real content (## Gotchas) instead of orphan chrome. The toolkit framing already lives in the conformant head blockquote.
Head/badges/images unchanged (already conformant); no mermaid; command/flag accuracy verified against the cobra surface.

Part 2 — docs/site/ depth tree

docs/site/install.md (new) — full install guide: Homebrew, manual (just local-install), the eval "$(wt shell-init)" shell-wrapper step, the cross-tool note, and the relocated fab-kit-origin context. Renders at /tools/wt/install.
docs/site/workflows.md (new) — deep usage: per-flag command reference (incl. wt update), the wt create --base start-point table, the wt open launcher matrix, and in-depth gotchas. Renders at /tools/wt/workflows; target of the README link.

Docs-only: no code, tests, or CI touched. Both new pages follow the closed-set rules (internal links stay inside docs/site/, external links absolute, neither is a reserved page name).

🤖 Generated with Claude Code

Conforms the repo to shll.ai's README-extraction contract, which renders the /tools/wt/ pages by mechanically pulling a slice of README.md and the docs/site/** tree on a daily schedule (nothing is hand-copied). Part 1 — README fixes: - Rewrite the relative docs/specs/cli-surface.md link (line 77) into a natural docs/site/workflows.md link. docs/specs/ is never pulled and the README slice is not closure-linted or rewritten, so the old link rendered as a live 404 on the site with no warning (contract §9.1.2 / directive rule 5). - Remove the trailing --- separator + repeated toolkit-footer blockquote so the pulled slice ends on real content (## Gotchas) instead of orphan chrome. The toolkit framing already lives in the conformant head blockquote. Part 2 — docs/site depth tree (the contract's encouraged Part 2): - docs/site/install.md (new) — full install guide: Homebrew, manual install, the shell-wrapper eval step, the cross-tool note, and the fab-kit origin. - docs/site/workflows.md (new) — deep usage: per-flag command reference, the wt create --base table, the wt open launcher matrix, wt update behavior, and in-depth gotchas. Docs-only: no code, tests, or CI touched. Nothing in shll.ai is modified — it pulls automatically.

Copilot

Pull request overview

This PR updates the repository’s documentation layout to conform to shll.ai’s README-extraction contract by removing a site-breaking README link and adding a conformant docs/site/** depth tree that shll.ai can render as /tools/wt/*.

Changes:

Replaced the README’s relative link to docs/specs/ with a link into docs/site/ (docs/site/workflows.md).
Removed the trailing README footer block so the extracted slice ends on real content.
Added docs/site/install.md and docs/site/workflows.md to provide on-site install + full command/flag depth.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
README.md	Fixes site-escaping link and removes orphan footer content.
docs/site/install.md	Adds a pulled install page for shll.ai rendering.
docs/site/workflows.md	Adds a pulled workflows/command-reference page for shll.ai rendering.
fab/changes/260608-pj57-shll-readme-conformance/intake.md	Captures the conformance rationale and requirements for the change.
fab/changes/260608-pj57-shll-readme-conformance/plan.md	Documents the implementation plan and acceptance checks.
fab/changes/260608-pj57-shll-readme-conformance/.status.yaml	Tracks fab pipeline status for the change.
fab/changes/260608-pj57-shll-readme-conformance/.history.jsonl	Records fab stage transitions/events for the change.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sahil-noon · 2026-06-08T10:16:37Z

+|---------|---------|
+| `wt create [branch]` | Create a worktree as a sibling of the main repo. |
+| `wt list` | List all worktrees with name, branch, and path. |
+| `wt open [name\|path]` | Open a worktree (or any directory) in a detected app. |


Skipped — incorrect for GFM. In a GFM table cell, row parsing runs before inline-code parsing, so an unescaped | is treated as a column delimiter even inside backticks; \| is the required escape and renders as a literal pipe with no visible backslash. Verified via GitHub's GFM API: the escaped form renders <code>name|path</code> cleanly, while removing the escape splits the cell and breaks the code span (name / path] across two columns). This is also the established repo convention (README.md, docs/specs/cli-surface.md). Astro Starlight (shll.ai's renderer) uses remark-gfm with the same semantics.

sahil-noon · 2026-06-08T10:16:38Z

+| `--worktree-init <true\|false>` | `true` | Run the worktree init script after creation. |
+| `--worktree-open <prompt\|default\|skip\|<app>>` | `prompt` (`skip` under `--non-interactive`) | What to do after creation: show the app menu, open in the detected default, skip, or open in a named app (e.g. `code`, `cursor`). |


Skipped — incorrect for GFM. In a GFM table cell, row parsing runs before inline-code parsing, so an unescaped | is treated as a column delimiter even inside backticks; \| is the required escape and renders as a literal pipe with no visible backslash. Verified via GitHub's GFM API: the escaped form renders <code>name|path</code> cleanly, while removing the escape splits the cell and breaks the code span (name / path] across two columns). This is also the established repo convention (README.md, docs/specs/cli-surface.md). Astro Starlight (shll.ai's renderer) uses remark-gfm with the same semantics.

sahil-noon · 2026-06-08T10:16:39Z

+| `--status` | `false` | Add a Status column: `*` for dirty, `↑N` for unpushed commits. Slower (forks git per worktree, parallelized). Mutually exclusive with `--path`. |
+| `--path <name>` | (none) | Print only the absolute path for the named worktree. Mutually exclusive with `--json` and `--status`. |
+| `--json` | `false` | Emit a JSON array of worktree records (`name`, `branch`, `path`, `is_main`, `is_current`; plus `dirty`/`unpushed` when `--status` is set). Mutually exclusive with `--path`. |
+| `--sort <recent\|name\|branch>` | (none) | Order non-main worktrees by most-recently-modified, name, or branch. |


Skipped — incorrect for GFM. In a GFM table cell, row parsing runs before inline-code parsing, so an unescaped | is treated as a column delimiter even inside backticks; \| is the required escape and renders as a literal pipe with no visible backslash. Verified via GitHub's GFM API: the escaped form renders <code>name|path</code> cleanly, while removing the escape splits the cell and breaks the code span (name / path] across two columns). This is also the established repo convention (README.md, docs/specs/cli-surface.md). Astro Starlight (shll.ai's renderer) uses remark-gfm with the same semantics.

sahil-noon · 2026-06-08T10:16:41Z

+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--app <name\|default>` | (none) | Open directly in the named app, skipping the menu. `default` selects the auto-detected default. Incompatible with the main-repo selection menu. |


Skipped — incorrect for GFM. In a GFM table cell, row parsing runs before inline-code parsing, so an unescaped | is treated as a column delimiter even inside backticks; \| is the required escape and renders as a literal pipe with no visible backslash. Verified via GitHub's GFM API: the escaped form renders <code>name|path</code> cleanly, while removing the escape splits the cell and breaks the code span (name / path] across two columns). This is also the established repo convention (README.md, docs/specs/cli-surface.md). Astro Starlight (shll.ai's renderer) uses remark-gfm with the same semantics.

sahil-noon · 2026-06-08T10:16:42Z

+| `--delete-branch <true\|false\|auto>` | `auto` | Delete the associated local branch. `auto` deletes only when the branch name matches the worktree name. |
+| `--delete-remote <true\|false>` | `true` | Delete the remote-tracking branch when the local branch is deleted. |


Skipped — incorrect for GFM. In a GFM table cell, row parsing runs before inline-code parsing, so an unescaped | is treated as a column delimiter even inside backticks; \| is the required escape and renders as a literal pipe with no visible backslash. Verified via GitHub's GFM API: the escaped form renders <code>name|path</code> cleanly, while removing the escape splits the cell and breaks the code span (name / path] across two columns). This is also the established repo convention (README.md, docs/specs/cli-surface.md). Astro Starlight (shll.ai's renderer) uses remark-gfm with the same semantics.

Wire the README's concise sections to the deeper pulled pages: - Install section now points to the full install guide (docs/site/install.md → /tools/wt/install on the site). - Command reference now carries two links with distinct roles: the auto-generated full flag/exit-code reference at https://shll.ai/tools/wt/commands/ (the site-owned `commands` page), and the hand-written --base/wt-open depth in docs/site/workflows.md (→ /tools/wt/workflows). Both docs/site links use the natural docs/site/<p>.md form (the site rewrites them to /tools/wt/<p>; they resolve to real files on GitHub) and are plain inline links — avoiding the badge-wrapped / reference-style shapes the extractor does not rewrite.

sahil87 added 2 commits June 8, 2026 15:39

Update ship status and record PR URL

c575a18

sahil-noon marked this pull request as ready for review June 8, 2026 10:10

sahil-noon requested a review from Copilot June 8, 2026 10:11

Copilot started reviewing on behalf of sahil-noon June 8, 2026 10:11 View session

Copilot AI reviewed Jun 8, 2026

View reviewed changes

sahil-noon merged commit 25e809a into main Jun 8, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: shll.ai README-extraction conformance#22

docs: shll.ai README-extraction conformance#22
sahil-noon merged 3 commits into
mainfrom
260608-pj57-shll-readme-conformance

sahil-noon commented Jun 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

sahil-noon Jun 8, 2026

Uh oh!

sahil-noon Jun 8, 2026

Uh oh!

sahil-noon Jun 8, 2026

Uh oh!

sahil-noon Jun 8, 2026

Uh oh!

sahil-noon Jun 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		\| `--worktree-init <true\\|false>` \| `true` \| Run the worktree init script after creation. \|
		\| `--worktree-open <prompt\\|default\\|skip\\|<app>>` \| `prompt` (`skip` under `--non-interactive`) \| What to do after creation: show the app menu, open in the detected default, skip, or open in a named app (e.g. `code`, `cursor`). \|

		\| `--delete-branch <true\\|false\\|auto>` \| `auto` \| Delete the associated local branch. `auto` deletes only when the branch name matches the worktree name. \|
		\| `--delete-remote <true\\|false>` \| `true` \| Delete the remote-tracking branch when the local branch is deleted. \|

Conversation

sahil-noon commented Jun 8, 2026

Meta

Summary

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

sahil-noon Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

sahil-noon Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

sahil-noon Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

sahil-noon Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

sahil-noon Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants