8000 docs(guide): rewrite getting started as a command-first quickstart by norrietaylor · Pull Request #3259 · gominimal/minimal · GitHub
[go: up one dir, main page]

Skip to content

docs(guide): rewrite getting started as a command-first quickstart - #3259

Closed
norrietaylor wants to merge 5 commits into
docs/glossaryfrom
docs/command-first-quickstart
Closed

norrietaylor wants to merge 5 commits into
docs/glossaryfrom
docs/command-first-quickstart

Conversation

@norrietaylor
@norrietaylor norrietaylor commented Nov 10, 2026 •
Copy link
Copy Markdown
Member

What

Rewrites docs/guide/getting-started.md from three paragraphs of product description into six steps with one command each:

  1. install
  2. min init
  3. min add --session claude
  4. min session start
  5. claude
  6. min box list / min box attach / min box rm

The steps use only BCLI commands that are already on main (min session start, min box list|attach|rm), not the session verbs that BCLI-042 removes. The first use of each term links to its glossary entry. The full docs update waits for BCLI to land.

It ends with at most three "next" links.

Also switches docs/guide/agents.md from claude-code to claude, so the two pages name the same package. The other sentences flagged by Vale in that file are rewritten so it has zero alerts. Its "session" wording stays until the guide rewrite.

Stacked on the glossary PR because it links to the glossary; the base retargets to main when that PR merges.

Why

User feedback: the docs are "walls of text" that point back and forth between large pages. The old getting-started page had no command on it, and the first runnable command was in setup.md, after a long explanation of minimal.toml.

Verification

  • just lint-prose docs/guide/getting-started.md docs/guide/agents.md: 0 alerts.
  • The claude package is a metapackage that installs claude-code and claude-code-minimal-plugin (gominimal/pkgs packages/claude/build.ncl).

Not yet verified, so this stays a draft until they are checked:

  • No dry run yet on a clean macOS or Linux host.
  • min init still writes the old [session] table name, and release 0.8 prints a hint each time it reads it. A new user will see that hint on the first activate.
  • Not checked: whether min add --session writes to the table that min init created.

Six steps, one command each: install, min init, min add --session
claude, activate, run the agent, list/attach/destroy.
@coderabbitai
coderabbitai Bot commented Nov 10, 2026
Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

claude installs Claude Code plus its Minimal plugin. Also clears the
file's Vale alerts.
The `claude` package is Claude Code plus the Minimal plugin for it.

## 4. Start a box

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should use BCLI commands and reuse the glossary terms

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 8d39e29. Steps 4 and 6 now use min session start, min box list, min box attach and min box rm, all BCLI commands already on main. None of the session verbs that BCLI-042 removes are left. The first use of box, stack, minimal.toml, package and session each links to its glossary entry. The glossary itself now says min box exec and local (b56dbd2).

min session start, min box list, min box attach and min box rm replace
the session verbs BCLI-042 removes. First uses link to the glossary.
@bryan-minimal bryan-minimal left a comment
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read at 8d39e29, each of the six commands checked against the CLI on main and the package against the registry.

Every command is one a person can type today. min init prompts before it writes only on a terminal not told --no-input, which is what "It asks before it writes" says for the person at a terminal. min add --session claude is --session on AddArgs, and packages/claude exists in gominimal/pkgs beside the older claude-code, so switching docs/guide/agents.md to claude makes the two pages name the one package. min session start is the BCLI verb on main (T40 landed the override flags on it this week). min box list, min box attach with no argument ("omit it to attach to this project's box") and min box rm <box> [--force] are as the page shows them, --force included for a running box.

The rewrite does what it says. Six steps with one command each, the first use of each term linked to the glossary (#3258), three "next" links, and the agents.md sentences rewritten to zero Vale alerts without changing what they allow: the credential paragraph still says to pass the minimum and that activation gates each inherited value and patch against the user policy.

One note, not blocking: step 4 says the packages from step 3 are on the box's PATH; min add --session edits [defaults.session], so a project whose minimal.toml already has a session entry with its own packages gets them there, which is the same outcome; fine as written for a fresh min init.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0