Scripto docs
View as Markdown

Working with sections

The practical outline → get → set loop, addressing sections by anchor, inserting and moving, and reclaiming canvas-edited sections.

This guide is the ordered-sections model as a hands-on workflow — the loop an agent runs to edit a long article without ever handling the whole thing.

Map before you touch anything

Always start from the outline. It’s cheap (no bodies) and prints the anchors you’ll use:

scripto outline <id>
  Our launch  [draft] · 1240w

  a1b2c3d4  h1  Our launch                    52w
  e5f6a7b8  h2  What changed                 318w
  9c8d7e6f  h2  Why it matters               210w

Edit one section

An anchor is any unique prefix of a section id. Pull a section to a file, edit, push it back:

scripto section get <id> e5f6a7b8 -o sec.md
# edit sec.md …
scripto section set <id> e5f6a7b8 --file sec.md

If the new Markdown contains several headings, that one section splits into several in place — and the command echoes the fresh outline so the new anchors are in view.

Insert a new section

# Append:
scripto section add <id> --file conclusion.md
# Insert relative to an anchor:
scripto section add <id> --file aside.md --after e5f6a7b8
scripto section add <id> --file intro.md --before a1b2c3d4
echo "## Caveats\n\nText…" | scripto section add <id> --stdin --after 9c8d7e6f

Pass exactly one of --after / --before, or neither to append.

Move and remove

scripto section mv <id> 9c8d7e6f --before e5f6a7b8   # reorder
scripto section rm <id> e5f6a7b8                     # delete

A section can’t be moved relative to itself. Deleting the last remaining section leaves the article with one empty section so it stays editable.

Anchors that are ambiguous

If a prefix matches more than one section, the command fails with invalid-argument and a nextAction telling you to use a longer prefix:

✗ The section anchor "a1" is ambiguous.
  next: Use a longer anchor (more characters of the section id).

Re-run scripto outline <id> to see the current anchors.

Reclaiming a canvas-edited section

A section the human edited in the web canvas has source: html — section get returns its HTML and there’s no clean Markdown to reverse. To bring it back under Markdown authorship, just set it with fresh Markdown:

scripto section get <id> <anchor>        # inspect the HTML
scripto section set <id> <anchor> --file rewritten.md

The whole point of the loop is that your context stays proportional to the edit. Resist scripto articles update <id> --file whole.md unless you’re genuinely replacing the entire body — it re-splits everything and pulls the whole document into context.

Next