garden explain

Author a shareable walkthrough of a GitHub pull request

garden explain <github-pr-url>

Author a walkthrough — an evidence-backed reading guide someone follows instead of re-deriving intent from the diff — for a pull request on GitHub, and get a link to send them. The reader needs no garden account.

Bare ‘garden explain <url>’ fetches the PR’s diff with your GitHub credentials and prints a template scaffolded from it (one block per changed file — split, merge, and reorder them freely). Fill it in and pipe it back:

garden explain https://github.com/o/r/pull/7 > w.yaml <edit w.yaml> garden explain apply <slug> -f w.yaml

No checkout required: these commands work anywhere.

Flags

Flag	Type	Default	Description
`--allow-private`	bool	—	Share a private repository’s PR — the link exposes that code to anyone who has it
`--target`	string	—	Garden backend to talk to (prod\|dev); defaults to the checkout’s own target

`garden explain apply`

Write a shared walkthrough from a YAML/JSON document

garden explain apply <url|slug>

Write (replace) a shared walkthrough from a declarative document. Omit –file or pass ‘-’ to read stdin.

Document shape: summary: what this change does + the one thing to know confidence: medium # low | medium | high layout: top-down # top-down | bottom-up | sandwich critical_path: [b2] # block ids to read first blocks: # top-level roots — together they prove the PR

- id: b1
  title: parse the plan
  scope:
    - { path: cli/plan.go, lines: 90-140 }   # whole file if lines omitted
  intent: what it does and why — the claim
  attention: review         # skim | review | scrutinize
  risk: low                 # low | medium | high
  proof:                    # one kind per entry
    - test: plan_test.go::TestParse
    - command: "go test ./..."
    - pointer: { path: pkg/x.go, lines: 40-80 }   # any code that proves it
    - external: https://ci/run/1
    - note: reasoned only
  unproven: what wasn't verified
  children:                 # sub-blocks that prove this block (the tree)
    - id: b1a
      title: reject a corrupt plan
      scope:
        - { path: cli/plan.go, lines: 145-170 }
      intent: errors if the body was rewritten instead of verbs flipped
      attention: scrutinize
      risk: high
      proof:
        - test: plan_test.go::TestRejectsCorruption

‘attachment:’ proofs are not available here — a shared walkthrough has no repository to upload files to. Host the file and link it with ‘external:’.

Flags

Flag	Type	Default	Description
`-f, --file`	string	—	Walkthrough document (YAML or JSON); omit or ‘-’ to read stdin
`--target`	string	—	Garden backend to talk to (prod\|dev); defaults to the checkout’s own target

`garden explain list`

List your shared walkthroughs

garden explain list

Aliases: ls

Flags

Flag	Type	Default	Description
`--json`	bool	—	Output as JSON
`--limit`	int32	`50`	Maximum to list (max 200)
`--target`	string	—	Garden backend to talk to (prod\|dev); defaults to the checkout’s own target

`garden explain revoke`

Stop a share link resolving

garden explain revoke <url|slug>

Make a share link stop resolving. The slug is never reissued, so a revoked link is dead for everyone who has it.

Flags

Flag	Type	Default	Description
`--target`	string	—	Garden backend to talk to (prod\|dev); defaults to the checkout’s own target

`garden explain show`

Print a shared walkthrough

garden explain show <url|slug>

Flags

Flag	Type	Default	Description
`--target`	string	—	Garden backend to talk to (prod\|dev); defaults to the checkout’s own target