CLI Documentation Guidelines

Review or write CLI docs following these principles. CLI docs serve two audiences: newcomers running their first command, and experienced users scanning for flags.

Core Principles

All README Guidelines apply here. In addition:

1. Logical command ordering

Commands must appear in the order a user would run them. A command should never reference output or state from a command that appears later in the docs.

Wrong — stop appears before the user knows how to list:

smolvm stop <vm_id>
smolvm list

Right — create, inspect, then destroy:

smolvm create --name my-sandbox
smolvm list
smolvm stop my-sandbox

2. Introduce a concept before its flags

Show the base command before showing any flags or subcommands. Each flag is a new concept — don't introduce two flags in the same example unless they always go together.

Wrong — --os and --name are both new:

smolvm create --os debian --name my-debian-sandbox

Right — --name first, then a separate example for --os:

# Create a sandbox with a name
smolvm create --name my-sandbox

# Use a different OS image
smolvm create --os debian --name my-debian-sandbox

3. Show expected output after commands that produce it

When a command prints a value the user needs (an ID, a URL, a status), show it. The reader should never have to run the command to find out what it returns.

smolvm browser start --live
# Session: sess_a1b2c3
# Live view: http://localhost:6080

4. One topic per section

Don't mix sandbox lifecycle commands with browser session commands in the same section. Each distinct workflow gets its own heading.

5. Flags reference comes after prose explanation

Never lead with a flags table. Explain what the command does in plain language first, then list flags for readers who want to go deeper.

Review Checklist

• Commands appear in the order a user would run them
• Every placeholder (<vm_id>, <session_id>) is introduced by a prior command or clearly labelled as "output from the previous step"
• Each code block introduces at most one new flag or subcommand
• Commands that print useful output show that output as a comment
• Conceptually distinct workflows (e.g. sandbox vs. browser) are in separate sections
• Flags/options table, if present, appears after the prose description
• No jargon (SSH, TAP device, CIDR, firecracker, QEMU) without a plain-language explanation on first use

Output Format

For each violation found, output:

Line <N>: [rule violated]
  Current: <quote the problematic text>
  Fix: <suggested rewrite>

Then provide a revised version of any section that has more than one violation.

README Guidelines

Review or write README content following these principles. The goal is easy onboarding for both newcomers and advanced users.

Core Principles

1. Progressive disclosure of complexity

Structure content so readers can stop at any point and still have a working mental model. Each section should be usable on its own:

• Lead with the simplest outcome (one-liner, quickstart)
• Add detail in subsequent sections
• Advanced topics (integrations, internals, performance) come last
• Never require reading ahead to understand what's in front of you

2. One concept per code example

Each code block should demonstrate exactly one idea. If a snippet requires the reader to understand two or more new things simultaneously, split it.

Wrong — introduces sandbox creation AND environment variables at the same time:

with SmolVM(env={"API_KEY": "secret"}) as vm:
    vm.run("curl $API_KEY")

Right — teaches sandbox creation first, env vars in a separate example:

with SmolVM() as vm:
    vm.run("echo 'hello'")

3. Jargon-free language first, depth second

Explain every concept as if talking to a first-year CS student before using technical terms. Then go deeper if the reader needs it.

• Bad: "SSH host keys are accepted on first connection via TOFU"
• Good: "SmolVM automatically trusts new sandboxes on first connection to keep setup simple. (This is called trust-on-first-use, or TOFU — the same approach your browser uses for new websites.)"

4. Introduce before you use

Never use a value, flag, or identifier in a code block without explaining where it comes from. If a command prints a session_id, show that command before any command that takes session_id as input.

Review Checklist

When reviewing a README, check each section against these rules:

• Tagline: does it describe a single, concrete outcome?
• Intro paragraph: can a newcomer understand it without prior context?
• Quickstart: does it follow install → configure → first run, in that order?
• Each code block: does it introduce exactly one new concept?
• Each new identifier (<session_id>, <vm_id>): is it introduced before it's used?
• Jargon: is every technical term explained in plain language on first use?
• Sections: does complexity increase monotonically top-to-bottom?
• Examples table: are entries grouped by audience (getting started vs. advanced)?
• Footer: does it duplicate links that already appear at the top?

Output Format

For each violation found, output:

Line <N>: [rule violated]
  Current: <quote the problematic text>
  Fix: <suggested rewrite>

Then provide a revised version of any section that has more than one violation.

CLI Documentation Guidelines

Review or write CLI docs following these principles. CLI docs serve two audiences: newcomers running their first command, and experienced users scanning for flags.

Core Principles

All README Guidelines apply here. In addition:

1. Logical command ordering

Commands must appear in the order a user would run them. A command should never reference output or state from a command that appears later in the docs.

Wrong — stop appears before the user knows how to list:

smolvm stop <vm_id>
smolvm list

Right — create, inspect, then destroy:

smolvm create --name my-sandbox
smolvm list
smolvm stop my-sandbox

2. Introduce a concept before its flags

Show the base command before showing any flags or subcommands. Each flag is a new concept — don't introduce two flags in the same example unless they always go together.

Wrong — --os and --name are both new:

smolvm create --os debian --name my-debian-sandbox

Right — --name first, then a separate example for --os:

# Create a sandbox with a name
smolvm create --name my-sandbox

# Use a different OS image
smolvm create --os debian --name my-debian-sandbox

3. Show expected output after commands that produce it

When a command prints a value the user needs (an ID, a URL, a status), show it. The reader should never have to run the command to find out what it returns.

smolvm browser start --live
# Session: sess_a1b2c3
# Live view: http://localhost:6080

4. One topic per section

Don't mix sandbox lifecycle commands with browser session commands in the same section. Each distinct workflow gets its own heading.

5. Flags reference comes after prose explanation

Never lead with a flags table. Explain what the command does in plain language first, then list flags for readers who want to go deeper.

Review Checklist

• Commands appear in the order a user would run them
• Every placeholder (<vm_id>, <session_id>) is introduced by a prior command or clearly labelled as "output from the previous step"
• Each code block introduces at most one new flag or subcommand
• Commands that print useful output show that output as a comment
• Conceptually distinct workflows (e.g. sandbox vs. browser) are in separate sections
• Flags/options table, if present, appears after the prose description
• No jargon (SSH, TAP device, CIDR, firecracker, QEMU) without a plain-language explanation on first use

Output Format

For each violation found, output:

Line <N>: [rule violated]
  Current: <quote the problematic text>
  Fix: <suggested rewrite>

Then provide a revised version of any section that has more than one violation.

README Guidelines

Review or write README content following these principles. The goal is easy onboarding for both newcomers and advanced users.

Core Principles

1. Progressive disclosure of complexity

Structure content so readers can stop at any point and still have a working mental model. Each section should be usable on its own:

• Lead with the simplest outcome (one-liner, quickstart)
• Add detail in subsequent sections
• Advanced topics (integrations, internals, performance) come last
• Never require reading ahead to understand what's in front of you

2. One concept per code example

Each code block should demonstrate exactly one idea. If a snippet requires the reader to understand two or more new things simultaneously, split it.

Wrong — introduces sandbox creation AND environment variables at the same time:

with SmolVM(env={"API_KEY": "secret"}) as vm:
    vm.run("curl $API_KEY")

Right — teaches sandbox creation first, env vars in a separate example:

with SmolVM() as vm:
    vm.run("echo 'hello'")

3. Jargon-free language first, depth second

Explain every concept as if talking to a first-year CS student before using technical terms. Then go deeper if the reader needs it.

• Bad: "SSH host keys are accepted on first connection via TOFU"
• Good: "SmolVM automatically trusts new sandboxes on first connection to keep setup simple. (This is called trust-on-first-use, or TOFU — the same approach your browser uses for new websites.)"

4. Introduce before you use

Never use a value, flag, or identifier in a code block without explaining where it comes from. If a command prints a session_id, show that command before any command that takes session_id as input.

Review Checklist

When reviewing a README, check each section against these rules:

• Tagline: does it describe a single, concrete outcome?
• Intro paragraph: can a newcomer understand it without prior context?
• Quickstart: does it follow install → configure → first run, in that order?
• Each code block: does it introduce exactly one new concept?
• Each new identifier (<session_id>, <vm_id>): is it introduced before it's used?
• Jargon: is every technical term explained in plain language on first use?
• Sections: does complexity increase monotonically top-to-bottom?
• Examples table: are entries grouped by audience (getting started vs. advanced)?
• Footer: does it duplicate links that already appear at the top?

Output Format

For each violation found, output:

Line <N>: [rule violated]
  Current: <quote the problematic text>
  Fix: <suggested rewrite>

Then provide a revised version of any section that has more than one violation.