Move the demo workspace into the binary, installed by `cards demo` by somebox · Pull Request #32 · somebox/cards

somebox · 2026-10-12T07:02:23Z

Why

examples/demo-workspace was a second workspace in the repo beside .cards. The dev server, launch.json, board.sh and the pre-commit hook still defaulted to it, 11 Go test files shared it as a fixture, and the docs sent users there. It should be available to users who want it, and out of the way for development here.

What changes

For users: cards demo [dir] installs a sample workspace into a new directory (default ./cards-demo): an engineering board with six card types and a review lane, a welcome board, the jeeruh theme, and the review-notify hook / review-bot service examples. It seeds the sample cards (--seed=false for empty boards), refuses a non-empty directory, and prints how to open it. cards init ends with a one-line pointer to it.

For development: .cards is the only workspace in the repo. scripts/dev-server.sh and .air.toml no longer pass --seed, so a fresh clone's project board is never filled with sample cards. launch.json, board.sh, .gitignore, CONTRIBUTING and CLAUDE.md point at .cards only.

For tests: internal/demo/demotest.Dir(t) installs a fresh copy per test into t.TempDir(). review-bot_test.sh and both screenshot scripts run cards demo instead of copying the folder. The roadmap card-reference guard now reads .cards/backlog.jsonl. It had been checking the stale demo snapshot.

Not carried over: the demo's frozen backlog.jsonl, which was 191 of this project's own dev cards from 2026-07. The demo uses the existing sample cards instead.

Verification

go build ./..., go vet ./..., go test -race ./...: all green, including TestReviewBotScript against cards demo --seed=false (bot claim + comment, SSE resume after kill -9, supervisor stability).
New internal/demo tests: install writes the tree with executable launchers; a non-empty directory is refused; no logs, DB or snapshots are embedded (explicit //go:embed list, not all:).
End to end: cards demo → cards --workspace cards-demo list shows both boards and the five sample cards; a second cards demo into the same directory exits 1 with a clear message.
mkdocs build --strict clean.

Follow-up

The five sample cards are thin for the docs screenshots: tui-screenshots.sh now renders one card per lane, so the committed TUI images were left as they are. Card d74b2fe5 tracks a richer sample set and regenerating the screenshots from it.

Note

This conflicts with #30 in one file, .claude/launch.json: #30 reformats it and this PR repoints its cards-serve entry from the demo to .cards. Whichever lands second needs a sync; the resolution keeps #30's layout with ./.cards in that entry.

🤖 Generated with Claude Code

examples/demo-workspace was a second workspace beside .cards: the dev server, launch.json, board.sh and the pre-commit hook still defaulted to it, 11 Go test files loaded it as a shared fixture, and the docs sent users there. It is now opt-in for users and out of the way for development. - internal/demo embeds the definitions (engineering + welcome boards, seven card types, the jeeruh theme) and the review-notify / review-bot extension examples. `cards demo [dir]` (default ./cards-demo) installs them into a new directory, seeds the sample cards, and prints how to open it; --seed=false leaves the boards empty. It refuses a non-empty directory. `cards init` ends with a one-line pointer to it. - Tests install a fresh copy per test through internal/demo/demotest and Go removes it; review-bot_test.sh and the screenshot scripts run `cards demo` instead of copying the folder. The roadmap card-reference guard now checks .cards/backlog.jsonl — it was checking the stale demo snapshot. - The frozen backlog.jsonl (191 dev cards from 2026-07) is not carried over. - dev-server.sh and .air.toml no longer pass --seed, so a fresh clone's project board is never filled with sample cards; launch.json, board.sh, .gitignore, CONTRIBUTING and CLAUDE.md point at .cards only. - Live docs switch to `cards demo`; docs/archive and dated sprint plans stay as history. Card 3a4064fe. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🟡 Changes recommended

The advertised cards demo <dir> --seed=false argument order silently ignores the seed flag.

1 open finding

Parse directory and trailing flags; reject extra arguments · New

What changed in this PR

Moves the demo workspace into the binary and adds cards demo to install isolated sample workspaces.

Changes:

Adds embedded demo assets, installer, seeding, and CLI integration.
Migrates tests and screenshot tooling to fresh demo installations.
Repoints development tooling and documentation to .cards or cards demo.

File	Description
`scripts/tui-screenshots.sh`	Installs demo for TUI captures.
`scripts/site-screenshots.sh`	Installs demo for site captures.
`scripts/review-bot_test.sh`	Tests bot against installed demo.
`scripts/dev-server.sh`	Uses `.cards` without seeding.
`scripts/board.sh`	Removes obsolete demo reference.
`README.md`	Documents `cards demo`.
`internal/tui/tui_test.go`	Uses isolated demo fixture.
`internal/mcp/parity_test.go`	Uses isolated demo fixture.
`internal/mcp/mcp_test.go`	Uses isolated demo fixture.
`internal/mcp/instructions_test.go`	Uses isolated demo fixture.
`internal/httpapi/render_golden_test.go`	Uses isolated demo fixture.
`internal/httpapi/openapi_coverage_test.go`	Uses isolated demo fixture.
`internal/httpapi/httpapi_test.go`	Uses isolated demo fixture.
`internal/httpapi/breaches_temporal_test.go`	Uses isolated demo fixture.
`internal/docaudit/startersync_test.go`	Audits embedded definitions.
`internal/docaudit/docaudit_test.go`	Audits project backlog references.
`internal/demo/demotest/demotest.go`	Adds per-test demo installer.
`internal/demo/demo.go`	Embeds and installs demo assets.
`internal/demo/demo_test.go`	Tests installation safeguards.
`internal/demo/assets/README.md`	Adds installed demo guidance.
`internal/demo/assets/definitions/workspace.json`	Defines demo workspace.
`internal/demo/assets/definitions/themes/jeeruh.json`	Adds theme manifest.
`internal/demo/assets/definitions/themes/jeeruh.css`	Adds demo theme CSS.
`internal/demo/assets/definitions/extensions.json`	Declares example extensions.
`internal/demo/assets/definitions/card-types/task.json`	Adds welcome task type.
`internal/demo/assets/definitions/card-types/research-goal.json`	Adds research type.
`internal/demo/assets/definitions/card-types/programming-task.json`	Adds programming type.
`internal/demo/assets/definitions/card-types/infra-task.json`	Adds infrastructure type.
`internal/demo/assets/definitions/card-types/frontend-task.json`	Adds frontend type.
`internal/demo/assets/definitions/card-types/data-task.json`	Adds data type.
`internal/demo/assets/definitions/card-types/api-task.json`	Adds API type.
`internal/demo/assets/definitions/boards/welcome.json`	Defines welcome board.
`internal/demo/assets/definitions/boards/engineering.json`	Defines engineering board.
`internal/demo/assets/.cards/logs/.gitignore`	Excludes extension logs.
`internal/demo/assets/.cards/ext/review-bot.sh`	Adds bot launcher.
`internal/demo/assets/.cards/ext/review-bot.mjs`	Adds SSE review bot.
`internal/demo/assets/.cards/ext/notify.sh`	Adds review notification hook.
`internal/config/config_test.go`	Loads embedded demo fixture.
`internal/cli/cli_test.go`	Uses embedded demo fixture.
`docs/using-cards.md`	Documents demo command.
`docs/reference/INTEGRATOR-REFERENCE.md`	Updates demo source path.
`docs/reference/implementation-status.md`	Updates demo source path.
`docs/reference/cli.md`	Documents demo CLI.
`docs/reference/card-type-examples.md`	Links embedded examples.
`docs/guides/themes.md`	Updates theme guidance.
`docs/get-started.md`	Adds demo walkthrough.
`docs/extensions/index.md`	Updates extension examples.
`docs/examples/software-delivery.md`	Updates demo terminology.
`docs/examples/index.md`	Uses project workspace.
`docs/design/style-field.md`	Updates development command.
`docs/design/benchmark-suite.md`	Clarifies fixture guidance.
`docs/design-notes.md`	Separates dogfood and demo boards.
`docs/concepts/index.md`	Removes second-workspace references.
`docs/architecture/index.md`	Uses `.cards` examples.
`docs/architecture/design-system.md`	Updates board-theme example.
`docs/agents/mcp.md`	Uses `.cards` for MCP.
`CONTRIBUTING.md`	Documents project-board workflow.
`cmd/cards/reviewbot_test.go`	Updates integration-test guidance.
`cmd/cards/main.go`	Registers `demo` command.
`cmd/cards/init.go`	Points users to the demo.
`cmd/cards/demo.go`	Implements demo command.
`CLAUDE.md`	Updates repository guidance.
`CHANGELOG.md`	Records demo migration.
`.gitignore`	Removes obsolete demo ignores.
`.claude/launch.json`	Launches against `.cards`.
`.cards/definitions/themes/jeeruh.json`	Updates theme provenance.
`.cards/backlog.jsonl`	Synchronizes project-board state.
`.air.toml`	Stops seeding the project board.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+	withSeed := fs.Bool("seed", true, "fill the boards with sample cards and users (--seed=false for empty boards)")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	target := "cards-demo"
+	if fs.NArg() > 0 {
+		target = fs.Arg(0)


# Conflicts: # .claude/launch.json

`cards demo ./x --seed=false` — the order the usage line documents — seeded the workspace anyway: Go's flag package stops at the first positional, so --seed=false stayed in fs.Args() and was silently dropped, along with any other stray argument. parseWithDir parses flags on both sides of the one optional directory and rejects anything left over. `cards init` has the same bug on main (`cards init ./p --no-skill` installs the skill); tracked separately on card b00e7b12, which can reuse this helper. Addresses the Copilot review on #32. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI balanced review requested due to automatic review settings October 12, 2026 07:02

Copilot started reviewing on behalf of somebox October 12, 2026 07:02

View session

Copilot AI reviewed Oct 12, 2026

View reviewed changes

somebox and others added 2 commits October 12, 2026 12:42

Merge remote-tracking branch 'origin/main' into chore/demo-out-of-repo

f74ce1b

# Conflicts: # .claude/launch.json

somebox merged commit b1db200 into main Oct 12, 2026
4 checks passed

Navigation Menu

Repository navigation

Move the demo workspace into the binary, installed by `cards demo` - #32

Move the demo workspace into the binary, installed by `cards demo`#32
somebox merged 3 commits into
mainfrom
chore/demo-out-of-repo

somebox commented Oct 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Why

What changes

Verification

Follow-up

Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

somebox commented Oct 12, 2026 •

edited

Loading