Improve forked-doc shortcut customization workflow for agents

# Agent Workflow Feedback: Forked Shortcut Customization and Generated Agent Surfaces

## Summary

While customizing an existing forked tbd shortcut, the tbd v0.3.0 CLI behavior worked,
but the complete agent workflow was not obvious from one place in the docs.

The working flow was:

1. Edit `docs/tbd/shortcuts/.md`.
2. Run `tbd shortcut `.
3. Run `tbd shortcut --list`.
4. Run `tbd docs status`.
5. Run `tbd setup --auto`.
6. Commit the edited shortcut, any generated docs index update if needed, and generated
agent skill files.

The next release could make this workflow more explicit and reduce manual steps around
generated indexes and generated agent-skill surfaces.

## What Worked

- **Forked shortcuts are served immediately.** After editing
`docs/tbd/shortcuts/.md`, `tbd shortcut ` returned the customized content
without another cache step.
- **Shortcut list uses edited frontmatter.** `tbd shortcut --list` displayed the updated
`description` field from the forked shortcut.
- **Status classification is useful.** `tbd docs status` reported the edited shortcut
as `customized`, which made the local override visible.
- **`setup --auto` refreshes generated agent surfaces.** A clean run updated generated
skill files so future agents could see the new shortcut description in the generated
skill table.
- **The generated skill header is helpful.** The `DO NOT EDIT` banner on generated skill
files points back to `tbd setup`.

## Friction

- **The edit path is split across docs.** `docs/tbd/README.md` says forked docs can be
edited, `tbd-docs.md` explains fork states, and `new-shortcut.md` explains shortcut
authoring. None of them gives the full existing-shortcut customization workflow.
- **`new-shortcut.md` can send agents to the wrong place.** It mentions official package
shortcut locations and project-level `.tbd/docs/...` locations, while the active
forked-doc path in a configured repo is `docs/tbd/shortcuts/.md`.
- **The generated `docs/tbd/README.md` index did not refresh automatically.** The CLI
served the customized shortcut and updated generated skill tables, but the human
browsable `docs/tbd/README.md` shortcut description needed a manual one-line update.
- **Partial `setup --auto` success can look too successful.** In a sandboxed agent run,
`tbd setup --auto` printed permission warnings for generated skill/hook writes, then
ended with `All set!` and exit code 0. A second run with broader filesystem permission
completed cleanly. The first result was actionable but easy for an agent to misread as
complete.
- **There is no one-command validation for “future agents will see this.”** The correct
verification used several commands: `tbd shortcut`, `tbd shortcut --list`,
`tbd docs status`, `tbd setup --auto`, and searching generated skill files.

## Suggested Workflow Updates

### 1. Add an Existing-Shortcut Customization Section

Add this to `tbd shortcut new-shortcut`, `tbd-docs.md`, or both:

```text
To customize an existing bundled shortcut:

1. Edit docs/tbd/shortcuts/.md.
2. Run tbd shortcut to confirm the served content.
3. Run tbd shortcut --list to confirm the frontmatter description.
4. Run tbd docs status to confirm the document is customized.
5. Run tbd setup --auto to refresh generated agent skill surfaces.
6. Commit the edited shortcut plus generated skill file changes.
```

Include a separate note for new custom shortcuts so agents do not confuse existing
forked shortcuts with brand-new project-only shortcuts.

### 2. Refresh the `docs/tbd/README.md` Index Automatically

Add one of these options:

- `tbd docs refresh-index`
- automatic index refresh in `tbd setup --auto`
- automatic index refresh after `tbd docs status` detects changed frontmatter, behind an
explicit flag such as `--fix`

The current behavior leaves direct doc readers with stale descriptions unless agents
manually edit a generated index.

### 3. Add Agent-Surface Validation

Add a command or flag that checks whether generated agent surfaces reflect forked docs:

```bash
tbd setup --auto --check
tbd docs status --agent-surfaces
tbd doctor --agent-surfaces
```

The check should report stale generated files when a forked shortcut description differs
from generated skill files or other configured agent surfaces.

### 4. Make Partial Setup Success Explicit

When `tbd setup --auto` cannot write a generated file, prefer one of these behaviors:

- exit non-zero
- print `All set with warnings`
- show a final `Next action` line naming the failed write path and suggesting a rerun
with broader filesystem permission

Agent sandboxes make this common. A successful exit with warnings is easy for agents to
miss.

### 5. Distinguish Three Doc Locations

Document the difference between:

- **Forked managed docs:** `docs/tbd//.md`, tracked and served by tbd.
- **Generated integration surfaces:** `.agents/`, `.claude/`, `.codex/`, refreshed by
`tbd setup --auto`.
- **Internal cache and metadata:** `.tbd/`, managed by tbd and not the primary edit
surface for agents.

This would reduce uncertainty around whether agents should edit `docs/tbd`, `.tbd/docs`,
or generated skill files.

### 6. Add a Shortcut-Authoring Validation Checklist

Add a reusable checklist for shortcut edits:

```bash
tbd shortcut
tbd shortcut --list
tbd docs status
tbd setup --auto
git diff -- docs/tbd/shortcuts/.md .agents/skills/tbd/SKILL.md .claude/skills/tbd/SKILL.md
```

The checklist should state that generated files should be committed when the repository
tracks them.

## Suggested Agent Documentation Updates

- In the generated tbd skill, expand the `Documentation` command table with a line for
existing shortcut customization:
`Edit docs/tbd/shortcuts/.md, validate with tbd shortcut , then run tbd setup --auto`.
- In `new-shortcut.md`, separate “new shortcut” from “customize existing shortcut”.
- In `tbd-docs.md`, add a short “agent playbook” for updating forked guidelines,
shortcuts, and templates.
- In generated setup output, name the files that changed so agents know what to stage.

## Suggested Acceptance Tests

- Editing `docs/tbd/shortcuts/example.md` changes `tbd shortcut example` output.
- Editing the shortcut `description` changes `tbd shortcut --list`.
- `tbd docs status` reports edited forked docs as `customized`.
- `tbd setup --auto` updates generated skill tables from customized shortcut
descriptions.
- `tbd setup --auto` reports a non-ambiguous failure state when generated skill writes
fail.
- The generated `docs/tbd/README.md` index can be refreshed without manual editing.

## Priority

1. Clarify the existing-shortcut customization workflow in docs.
2. Make partial `setup --auto` failures unambiguous.
3. Add an index refresh path for `docs/tbd/README.md`.
4. Add agent-surface validation for generated skills and hooks.