Reference

Checks run in three groups: the machine’s, the project’s and the space’s. Getting started says what each checks, and Troubleshooting gives each fix. Plain bb doctor fails only on a failure.

--write is the check before anything writes to Storyblok. Run it in the project. These must pass, and a warning or a skip counts as a failure:

• storyblok-token, or project-storyblok-token when the token is in the project’s .env
• project-backpack, project-storyblok-token and project-env-ignored. A shell token that overrides a different one in .env only warns, and doesn’t block: space-access checks the token sb-mig will use
• space-id and space-access

It ends with Ready to write to Storyblok., or the checks that aren’t ready. Its exit code follows that alone: 0 ready, 1 not. Other failures, such as github, still show but don’t fail the run. Each blocker is an error, check-failed or not-ready-to-write, and data.write is { ready, blockers }. --write and --fix also set the project up for Chaperone and the slot component (see the Chaperone preset).

Notes on single checks:

• figma-mcp is left out under --write. Plain doctor says Figma: checked when the frame is read: it passes with a local connector or plugin, and skips neutrally otherwise. A local MCP that needs sign-in doesn’t warn: your claude.ai connector can still work.
• With the token in .env, storyblok-token passes with Covered by the project's .env (STORYBLOK_OAUTH_TOKEN).
• Three advisory checks never block a write, in plain doctor or --write:

The space and the token:

• The space id comes from --space, then spaceId in storyblok.config, space.id in .backbase/config.json, STORYBLOK_SPACE_ID in your shell, then in the project’s .env. An empty source falls through; an invalid value fails. The catalog, the asset commands and story validation use the same order, without --space.
• Doctor evaluates storyblok.config as bb catalog does. Like sb-mig, it loads .env first without overriding your shell.
• It asks the Management API sb-mig uses: storyblokApiUrl in storyblok.config, then NEXT_PUBLIC_STORYBLOK_MANAGEMENT_API_URL, then the EU API. space-access gives Storyblok 10 seconds to answer.
• The token goes only over https, and only to Storyblok’s Management API: EU https://mapi.storyblok.com/v1, US https://api-us.storyblok.com/v1, CA https://api-ca.storyblok.com/v1, AP https://api-ap.storyblok.com/v1, CN https://app.storyblokchina.cn/v1 (and localhost or 127.0.0.1, for tests). Any other host, or plain http, fails space-access and the token isn’t sent. sb-mig’s own list has no Canada.
• Doctor never prints a token: not in the table, the JSON or the errors.

Nothing is written to Storyblok.

It runs its steps in order and stops at the first that fails, with the step’s message and its fix. It checks the folder first, then the machine checks it needs (node and git), before it writes anything. It never overwrites a file. Troubleshooting has each way it stops.

Use --component <blok> to see one blok, including what only Backpack’s React has, such as React only: CardFooter.variant: testimonial: a lead to check, not a fact, since a wrapper may map its own option names. data.stalePresets lists presets that name bloks Backpack 4 doesn’t have.

The knowledge pack

bb catalog --knowledge --out .backbase/knowledge.md compiles the catalog into the compact text the agent reads to choose bloks and presets and write design values, one line per blok:

- sb-tag | fields: label, icon:asset-selector(icons), aria_label | design: $d2, $d202, $d185, $d99, $d16, $d13, $d1 | placement: $p11 | parents: sb-card-header,sb-content-card,sb-flex-group,…

• What many bloks share is said once: $o option sets, $c sets of bloks, $d design subfields, $p subfields a blok has only under some parents. A colour picker lists its datasource’s real names. A preset manifest ends it, with the space’s presets too under --space-presets.
• --sections adds a colour map: each semantic variable the frame uses, and the colors entry its theme points at (color-system-surface-brand-accent-3 → Color/Red/Lightest (100)). Where the frame paints it another colour, the line ends ≠ frame #hex, then | write <name> when a colors entry has that hex, or | ≈ approximation, which the compose report lists. It never guesses.
• <house_style> holds how Backpack’s own presets are built: rules that hold at least 90% of the time over at least five bloks, with their counts, such as (9/9), and one hand-ruled hero rule marked CURATED. Compose follows the frame where it states a layout, and the house style where it’s silent.
• <section_grid> and <flex_alignment> come from the render table: what a position’s numbers are at each breakpoint (in 4.11.0, lines 0–6 at s and m, 0–16 from l, full bleed [0,6] and [0,16]), and which field moves a flex box’s children which way (in sb-flex-group, align is the vertical one).
• It’s scoped to what the root blok holds, page unless --root, and stays under 62,500 characters for an ILS-sized project.

When the catalog goes stale

The catalog and the pack record what they were compiled from: Backpack’s version, a hash of every file bb catalog read (Backpack’s schemas and what they load, storyblok.config, your schemas and datasources and their imports, component-list.ts, component-map.exceptions.json, backbase.placements.json, .backbase/render-semantics.json and the space-presets file), and the bb that compiled them. Line endings don’t count.

• Every command that takes --catalog refuses a catalog saved for another Backpack, or before a schema changed: catalog-stale, naming the versions or the files, and ending with the command that rebuilds it. One from another bb is still used when its Backpack matches.
• --out writes through a temporary file, so nothing reads half a catalog. --if-stale rebuilds only when the fingerprint differs, and says why in data.rebuilt and data.why.
• The skills rebuild both before they use them, and tell you in one line. bb doctor’s catalog check warns about a stale catalog.

A design value’s label isn’t its px on the page. In Backpack 4.11.0, item_spacing: s pads each list row 16px above and below, so rows sit 32px apart; item_flex: auto is Fill; sb-content-group puts no gap between its children; a card body pads 24px. bb’s render table says what each blok and value renders, in CSS and px, on which element. bb catalog shows it as renderSemantics, bb story design get under each subfield, and the knowledge pack in <field_spacing>. Compose and refine match the frame’s px to what a value renders, not to its label.

bb ships the table for 4.11.0. This command builds it from the project’s own Backpack, rendering with its wrappers on your machine, and bb catalog uses it from then on. Nothing is fetched or written to Storyblok. A table for another Backpack is ignored with a warning, and with none at all, the catalog, the pack and design get say so.

It checks the file against the sections contract.

The read skill runs a read-only script through your Figma connector for each part, and saves its output as figma-design.raw.json beside sections.json. This turns it into each section’s design and copy, offline. Both are optional.

copy is every visible text layer, in order, as { "id", "lines" }, nothing cut. Inside an instance, a node id starts with the instances it sits in (I2058:22115;3412:9002), which is how bb story fill tells one card from the next.

A large part is read in pages, and this puts them back together, up to 600 layers a section. When a section still isn’t whole, truncated is true and the agent tells you. The read never writes to Figma: a test checks the script for every Plugin API call that could.

The read skill downloads the original image fills with your Figma MCP’s download_assets. This matches the files by their bytes first, then by hash, node id or layer name, writes images.json beside sections.json, and lists what it couldn’t match in data.unmatched. A video is exported as a PNG poster of its node alone, without the player’s controls, and matched by node id, with note: "poster of a video".

It checks the plan contract, and warns when a blok lacks a required child, or the design fit is missing (design-fit-missing) or stale (design-fit-stale). A structure that selects a stale preset fails. A warning or a gap never fails the plan.

Design fit says whether the planned bloks’ design options can make each part look like the frame. For each entry with a design read, it pairs the Figma layers with the planned bloks in reading order and judges each fact: layout, spacing, colours, radii, strokes, shadows, overlays, text styles and variants.

• exact: an option expresses it.
• approximate: the nearest option stands in, such as a 3px gap as xxs (4px). A spacing, gap or radius off the scale is never written silently: it records the px, the field and the step (offScale), and each is a request to GCS. Halfway between two steps, padding and margins take the step Backpack’s presets use more (the ILS 96px padding is xxxl, 128), and gaps and radii the smaller. A colour takes the nearest entry by ΔE00 only within 10.
• gap: nothing can express it, such as a gradient border or an overlay on an image. Each is a request for the Backpack team.

A section’s fit is its worst fact’s. Colours are judged against .backbase/datasources.json, or --datasources, else the catalog’s datasources, alpha included: #191919 at 65% matches rgba(25, 25, 25, 0.65).

--write-design-fit stores each fit in the entry’s designFit once the plan passes: up to ten facts, gaps first, with the request evidence in requestFacts. A failing plan stores nothing (design-fit-not-stored).

Full bleed. A layer bleeds when its section starts at the frame’s left edge and it is as wide as the frame. Its blok goes on the section grid’s bleed lines, [0,6] at s and m and [0,16] at l in 4.11.0, and an sb-image takes viewport_size 100vw, at the frame’s breakpoint and below only. bb stores it in designFit.bleed, and compose writes it as it is.

With a stored design fit, the table gets a Design fit column (fits, ≈ 3, gap: stroke, overlay · ≈ 2, or — when not judged), and under it, per section: the design gaps, what another blok would fit, how many approximations (--approximations lists them), what wasn’t judged, the off-scale values (Padding: 96px, with every section and field) and what runs full bleed. Then the planned slots. The same lists are in .backbase/reports/gate-1.md.

Open questions. Confirming the plan never answers a question. Each is { "question", "recommended", "answer" }, the answer null until you give it. plan show marks each Recommended: … or Answered: …, and while any is open ends with a Confirmation that names each recommended answer: Confirm, with: the image bleeds. A yes to the Gate 1 card answers only the questions it showed, with the answers it showed. A question with no recommended answer needs your own words before the plan is confirmed: the agent never picks one for you.

After you confirm the plan, the analyse flow runs it and offers .backbase/requests/design-gaps.md. It works offline, from the plan, the frame’s sections.json and the catalog; only the icon manifest is fetched, once. One draft for each:

• capability a blok lacks, across sections, with the Figma evidence;
• value off a scale, per capability and px (Padding: 96px), with every section and field: ILS’s 96px padding is one request, not eleven;
• palette mismatch, for design and Backpack together. Palette drafts carry a TODO to recheck theme overrides before filing;
• icon that icons/bold doesn’t have (Icon: google), with the closest names. A global section’s icons ask for nothing;
• set of stale presets, with each file, component and unknown name.

Each sits under its key’s marker (<!-- backbase-request: padding-96px -->). Wrap and missing-primitive requests stay in plan.json. It rewrites only design-gaps.md, and keeps each Filed: link. Refresh an older plan first with bb plan validate <plan> --sections <file> --write-design-fit; it warns when you need to.

The requests go to GCS only through /backbase:upstream requests, after your yes. The analyse flow never files one, and filing blocks neither the plan nor Gate 2.

It writes nothing to the space. In order, it:

1. checks what bb doctor --write checks, and stops when the project isn’t ready;
2. checks the project’s sb-mig is 6.5.0-beta.25 or later (the boilerplate pins one that is);
3. runs sb-mig sync datasources --all --dry-run --json, then sb-mig sync components --all --presets --dry-run --json, with nothing on stdin and the checked space as STORYBLOK_SPACE_ID;
4. with --sections, plans the theme;
5. saves .backbase/space-plan.json and prints what it would create and update, what’s left out, the presets, the theme, the missing field plugins, every destructive change on its own line, the fingerprint and the exact bb space sync command.

• Destructive changes can lose content: field-removed, likely-rename, type-changed and whitelist-narrowed. The fingerprint hashes the space and every planned change, presets included.
• The approval is the plan’s exact approvalSentence, which names the fingerprint and every destructive change. A generic yes never approves a destructive change.
• Presets. sb-mig writes every preset by name on every sync, overwriting edits made in Storyblok, so the plan lists them by component. Stale presets are listed with their files, and approving the plan still writes them: the sentence says how many.
• --exclude drops a component and its destructive changes, and lists it in plans.excluded with your reason. The fingerprint covers the names, not the reasons. An unknown name is exclude-unknown.
• Field plugins. Each plugin a component’s top-level custom fields use is available, missing or unverified. It’s missing only when every listing of it assigns it to other spaces. A 401, 403 or 404 on a list leaves it unverified, never missing. Each missing one is in missingFieldPlugins, with the way round: install it, or --exclude the component.
• --components-only plans only the components, for the component stage, and its fingerprint binds that scope. It can’t go with --sections.

The theme part

Site Builder’s theme is the Settings story’s backpack-theme field, rebuilt from the colors-theme-light and colors-theme-dark datasources, whose user dimension holds the space’s overrides. So bb writes user values, then saves the Settings story’s field as a draft, rebuilt as the plugin rebuilds it (ADR 0031).

With --sections .backbase/figma/<node-id>/sections.json, for each semantic colour the frame paints with, it compares what the space paints today:

• set when the token has no user value, change when it has another, reset when the default is already the frame’s colour.
• The value is var(--color-<primitive>) for an exact colors match, else the hex, such as #E0D7F9. It never snaps to the nearest.
• Each colour of the frame’s own is offered as a custom-colors entry, such as Package (ILS) · System/Surface/Brand/Accent/3. The datasource is created when the space has none.
• Light theme only: dark keeps Backpack’s defaults, and a note says so. A translucent paint isn’t planned.
• A first sync plans no theme: plan again after it.
• A user value it replaces is lost from the space, so it’s named in the approvalSentence, listed with the destructive changes and named in the hook’s ask. .backbase/space-sync.json records each previous value.
• For each Settings story (settings, or <locale>/settings), the plan shows each token whose selected value changes. A missing one is a note, never an error.
• The fingerprint covers the theme’s writes, the values they replace and when each Settings draft was saved, so a change in the space after the plan makes bb space sync refuse.

Never --ssot.

It plans again, and refuses, exit 1, writing nothing, when:

• the fingerprint isn’t the approved one (plan-changed): plan again;
• the plan has destructive changes and no --allow-destructive (destructive-not-allowed). The agent passes it only after you approve each by name.

Then it runs sb-mig sync datasources --all --json and sb-mig sync components --all --presets --json, or names the components when some are excluded, and saves both reports in .backbase/space-sync.json.

• Errors, exit 1: component-failed for each component sb-mig couldn’t write, with --exclude as the way round (a missing field plugin’s 422 names the plugin, and fieldPluginFailures lists it); component-not-synced when sb-mig’s report lacks a component it was given; sync-failed for a whole step. When the datasources fail, the components don’t run. Nothing is rolled back.
• The theme is written last, even when a component failed. It’s skipped, theme-plan-again, when the sync wrote a datasource it was planned from, or someone changed a token or saved Settings since the plan. Only colour values are sent, and defaults never change. A failed write is theme-write-failed, in data.theme.
• Settings is saved with only its theme field changed, as a draft, never published. space-sync.json records previous and previousModel, to restore by hand.
• Storyblok has no conditional write, so the last save wins: a Settings tab opened before the sync holds the old theme, and saving it brings it back. Close Settings before the sync, reopen it after, and publish it yourself when you’re happy.

Safety. bb never runs sb-mig with --ssot, which deletes every component the code doesn’t have, and the content in them. No flag asks for it. The plugin’s hook blocks any command where sb-mig is followed by --ssot, however it’s run (npx, pnpm exec, dotenv --, find -exec, bash -c, a heredoc fed to a shell, npm run <script> -- --ssot or pnpm <script> --ssot), and lets text-only commands such as grep or git commit -m through. A package script with --ssot written into it is out of its reach, so the agent never runs the project’s sync scripts. The hook also blocks bb space sync without the plan’s fingerprint, or with --approved given twice, and makes Claude Code ask you first, naming the space and what it writes. The agent can’t answer that for you.

A colour picker stores the entry an author picks, with its id, and the ids are the space’s. This reads colors, custom-colors, colors-theme-light and colors-theme-dark, every page, as the picker reads them, read-only, through the same guarded client as bb doctor. It fails when the space has no colors: sync the datasources first. Run it after a sync. The file is a snapshot of the space, so git ignores it. bb story materialize and bb story validate read it.

It checks .backbase/plan.json against the last .backbase/space-sync.json for the project’s space: page and every blok the scaffold uses, preset children and required defaults included. A failed component the plan doesn’t use is a note. An absent, failed or skipped one it needs stops compose, and so do missing sync reports and dry runs. A stale preset is reported stale. Pass the same --root as scaffold.

Locale folders. With NEXT_PUBLIC_TRANSLATION_STRATEGY none or field, stories go at the root. With folder, they go in the default locale’s folder (languageMap.defaultLocale): compose saves the root folders, from Storyblok’s MCP, to .backbase/stories/folders.json, each with id, slug, is_folder and parent_id, and passes --folders. Until then the placement is pending, and it exits nonzero.

The result’s placement.parentId goes in the story file as story.parent_id before stamping, and placement.prefix is the full path, such as en/summer-camps. When that folder is missing, compose stops: create it in Storyblok and try again. Compose never creates it, and never falls back to the root.

It builds the approved plan as a story, offline, and writes two files in .backbase/stories/:

• <slug>.json, { "story": { "name", "slug", "content" } }: the page blok with the Reuse, Compose, Wrap and Create sections in page order, and a backbase-slot where a component is missing. A preset in code starts from its content.
• <slug>.report.json: what it composed, what it skipped and why (Global and Unsure aren’t composed), the images, every placeholder, the presets, what’s left for a person (todo), and bloks, the Figma layer each blok was built from.

What the plan doesn’t say is filled so the story validates, and the report lists each: copy placeholders that start [Backbase placeholder, empty images with the section’s name as alt, preset links emptied (they point into Backpack’s own space), required links as #backbase-placeholder, and required bloks and options from Backpack’s presets or the first allowed. Then it completes the story as bb story materialize does. Each section’s sb-section gets its name from the Figma section’s name, unique in the story: whats-included, then whats-included-2.

A preset from the space has no content in the catalog, so the report says to apply it in the editor. It never writes over a story it scaffolded before without --force.

It fills a story’s copy placeholders from the frame’s copy, offline, then the empty text its bloks show, such as a button’s label. It pairs each with a text layer by:

1. the story’s own words: a text that is a layer’s, word for word, is that layer;
2. node id: a repeated blok, such as a carousel’s slide, takes only its own instance’s layers;
3. instance order: the n-th card takes the n-th instance’s layers, when that’s the frame’s only run of instances there;
4. order, between the texts around it;
5. role: heading, body or label, from the blok and the layer’s text style.

It fills only when exactly one pairing fits, and otherwise lists the candidates. It never invents copy.

• It drops only what DROPPABLE_BLOKS lists, when the frame doesn’t show it: a tag, an eyebrow before a headline, then a card header the drops left empty. Anything else stays a placeholder, marked the frame has none.
• It fills an empty field only from SHOWN_TEXT (a button’s label, a link’s text, a tag’s label, a headline’s or text’s content), never a field with words in it or one nobody sees, such as an aria label.
• A text that looks like a placeholder, such as Heading, is the frame’s own, and is noted.
• The report’s fill lists filled, fieldsFilled, fieldsLeft, dropped, emptied and left, with the reasons. Running it again changes nothing settled.

It writes the story as the Storyblok editor would, so Backpack’s wrappers find every field they expect: StickyNavBarSB reads button[0], and the boilerplate’s GalleryImageSB reads blok.design.fields.

• Absent fields get their birth value: the schema’s default, else an empty value of the field’s type. A value that’s there is never touched.
• Designs become the lean backpack-breakpoints-v2 envelope, with only the subfields that have a value, and fields always there. The agent’s short dialect, "design": { "gap": { "s": "xl" } }, or one value for every breakpoint, is lifted into it. A subfield the blok’s actual parent doesn’t admit, such as position outside an sb-section, is taken out and reported. An editor’s full envelope is trimmed.
• Colours are stored as the picker’s selection of a colors or custom-colors entry, with the space’s ids, from .backbase/datasources.json. A hex, a theme token or an unknown name is a color-not-materialized error that names the closest entries.
• Sizes become { "value", "unit" } (a bare number is vh, as Backpack reads it), and %, vh and vw are clamped at 100. Numbers are clamped to their schema’s bounds. Links become the editor’s link (a placeholder becomes an empty link; another scheme, such as javascript:, is multilink-malformed). Section selectors become the plugin’s selectedSections.
• An unknown subfield or invalid value (design-unknown-subfield, design-invalid-value) writes nothing: fix it and run it again.

data.report lists every change and why. Running it again writes nothing. Stamp the story after it, never before. --sections <keys> completes only those sections and leaves the rest as they are, to the byte: edit passes it.

Icons. Write a bare kebab name, such as "icon": "fork-knife" (Figma’s ForkKnife). It stores the icon from EF’s icons/bold manifest, fetched once into .backbase/cache/icons-bold.json, which git ignores; --offline forbids the fetch. An unknown name warns (icon-unknown), PascalCase is icon-format, and a field that doesn’t take icons warns (icon-library).

It turns the frame’s auto-layout into the spacing values that render it, before anything renders, from the blok map and the render table. It refuses without a render table. It writes nothing to the story: one ops envelope, applied with bb story ops apply.

• Gaps take the container’s own field (gap, or item_spacing, which pads each row) at the value that renders them, else margins on the children.
• Padding goes to the blok that pads by default, such as a card body, else the layer’s own blok.
• Children with no layer, such as icons, and parts of a library instance stand for a frame layer only when they clearly match it.
• Fill and hug become item_flex, a fixed width an item_basis fraction only within a pixel, and a row frame direction: row.
• Every px rounds to the nearest token, with its error. A tie goes to the house style’s choice, and is listed in data.ties for a person to rule on. Values land at the frame’s breakpoint (1024px is l), never narrower.
• data.gaps is what no field can express, and data.skipped what it couldn’t plan, with why. Planning again after the apply changes nothing.

It lists the offered targets, the only bloks bb story ops apply will touch, each with its uid, component, path, section, and:

• props: the fields setProp may set, with their values. A rich text lists in lost what mark-up can’t say;
• children: each bloks field, with the components it takes;
• design: each design field’s allowed subfields, options and values.

--section, --component, --find <text> and --color <hex> (within ΔE00 5) filter, and combine. It answers in pages of at most --budget characters.

Ops are how an agent edits a local story: read the targets, write one envelope of typed ops, apply it all or nothing, and journal it so it can be undone. Ops never contact Figma or Storyblok, and change only the local file: the push still needs its plan and your yes.

bb story targets .backbase/stories/package-ils-11.json --section faq
bb story ops apply .backbase/stories/package-ils-11.json --ops ops.json
bb story ops undo .backbase/stories/package-ils-11.json --entry last
bb story validate .backbase/stories/package-ils-11.json --stamp

The envelope

{
  "summary": "Tighten the FAQ and bold the teacher's name",
  "ops": [
    { "op": "updateDesign", "targetUid": "4c9f04cd-…", "changes": { "item_spacing": { "s": "s", "m": null } } }
  ],
  "warnings": []
}

summary is what you say you did; bb measures what changed and journals both. Ops run in order, each with an optional reason. A uid is always an offered target or one minted earlier in the envelope: an agent never writes a _uid.

Colours take an entry’s name, "Color/Red/Lightest (100)", or a hex, which becomes the entry with that value, or the nearest within ΔE00 10, as design fit judges. Past that the op is repairable, unless it says "approximate": true. Each approximation is recorded. Without .backbase/datasources.json, the envelope is refused: run bb space datasources.

Rich text takes a small mark-up: a blank line starts a paragraph, a line break is a hard break, **bold**, *italic* or _italic_, and [label](url) to an https: or http: URL, a path, an #anchor or mailto:. A backslash escapes. Mark-up that doesn’t parse is repairable. It has no headings, lists or embedded bloks: a field that holds any refuses mark-up, so send Storyblok’s JSON document instead.

The answer, data.outcome:

• applied: written, its validation stamp dropped, journalled, with what the diff measured and the new bloks’ mintedUids;
• unchanged: nothing to do, and not a failure;
• repairable: nothing written. errors say what to fix, and data.legalTargets lists up to 30 targets to use instead;
• refused: nothing an envelope could fix.

The skills change a story only through ops, at most four repair rounds an envelope, and never by editing its JSON. Scaffold, fill and materialize are bb’s own generators; a bb test maps every story command to its ops, or the reason it’s exempt.

It restores the story file as it was before an entry, byte for byte (last by default), drops its stamp, and journals the undo, with undoOf. It refuses (ops-undo-stale) when a later entry or another edit changed the story since: --force restores anyway, and those changes are lost. An undo can’t be undone: apply its ops again.

The journal is .backbase/stories/<slug>.ops.jsonl, one line an envelope or undo, with a snapshot of the file before it in .backbase/stories/<slug>.ops/<n>.json. The last 50 entries keep theirs; an older one can’t be undone. A failed write puts everything back.

It shows a blok’s design subfields with their values, defaults, types and options at s, m and l, the shapes each accepts, its option fields, and what each spacing value renders: item_spacing: s → item li padding 16px top/bottom (32px between items). [] means the breakpoint isn’t supported. It never contacts Figma or Storyblok.

bb story design get .backbase/stories/package-ils-10.json --target package-hero
bb story design set .backbase/stories/package-ils-10.json --target package-hero gap@s=xl gap@m=l --note "Match the hero spacing"
bb story design revert .backbase/stories/package-ils-10.json --entry last --note "The fit got worse"

Targets start with an exact sb-section.name or any _uid (two matches fail, listing both), then an optional path of fields and indexes: package-hero/content.0.content.1, or package-hero/0.content.1 for short. Percent-encode /, . and % in a name.

An assignment is field[@s|m|l]=value. An exact field name wins, so size=l is the option field and design.size@s=l the design subfield; otherwise design.gap or plain gap. Without a breakpoint it sets every one the field supports; an option field takes none (as=h2). gap@s= clears one breakpoint, gap= all. Object values go in as JSON: 'spacing@s={"pt":"xl","pb":"l"}'.

All assignments are checked together, and one bad one refuses the whole call, changing nothing. Colours and text aren’t set here: use an ops updateDesign or setProp.

A call is one ops envelope and one journal entry, with --note as its summary. It drops the story’s stamp: validate and stamp it again before the next push, even after a revert.

It lists the design values every journal entry changed, sets, envelopes and undos alike, numbered (#3). The design log bb wrote before 0.15, <slug>.changes.jsonl, stays where it was, and bb page compare still reads it.

It’s bb story ops undo for one entry, byte for byte, whatever the entry was. It refuses when the story changed since (design-revert-stale: undo the later entries first), or when the entry is an undo, was undone already, or there’s nothing to undo (design-revert). It drops the stamp.

It checks a story against the project’s catalog, offline. The file is the content, or a wrapper with it under content or story.content. Each problem has the path of the key to fix, such as content.body[2].content[0].component, a code and a message. Errors fail the story, exit 1; warnings don’t. It also reports the story’s size and its five heaviest sections, which never fail it. It never calls Storyblok: options that live in the space are reported as unchecked.

bb story materialize clears missing-field, design-not-materialized, design-placement, the size codes, sections-not-materialized, a completable multilink-malformed, and, given the datasources, a named color-not-materialized. The agent fixes the rest: completion never guesses a value. Datasources from another space are refused (datasources-space).

Stamping

--stamp records a story that passes with no errors and no placeholders: the hash of its content in .backbase/stories/validated.json, with the project’s configured space and the story’s parent_id (0 for the root). It takes no --space, so a stamp can’t name another space, and without a configured space it fails. --allow-placeholders stamps with placeholders left, which compose passes only once you’ve agreed. A new stamp drops the stamps for other spaces.

bb story push writes exactly that content to that space, and the write guard lets nothing else through the MCP. Changing the content or the parent folder needs a new stamp; the name and slug don’t.

It drops the story's validation stamp, refuses a slug another local story file has, and never overwrites a file. The one way to change a slug: never edit the story JSON.

One name everywhere

A story file’s name, its story.slug and its slug in Storyblok are always the same: .backbase/stories/<slug>.json holds story.slug: "<slug>", and <slug>.remote.json records the story at that slug. In a folder, the name is the last part of the full slug: en/package-ils is package-ils.json. bb story validate, serve, push, page measure and page compare refuse a story whose names differ (slug-mismatch), with the fix: this command.

It also moves the story’s report, record, ops journal, snapshots and old design log, and drops its stamp: validate, stamp and plan the push again. It refuses a slug another local story has (slug-taken-locally), and never overwrites a file (slug-file-exists). For a story already in Storyblok, the next bb story push moves it there too, shown in the plan as a slug change. Compose and edit run it when their slug is taken, after asking you which.

The stories it doesn't have, such as settings, come from the real one once, with the project's public delivery token. It refuses to start when a file's name isn't its story's slug (slug-mismatch) or two files have one slug (serve-conflict): bb story slug fixes both. A story it answers from a file carries story._backbase. --print-env shows the lines that point the dev server at it; --write-env writes them to .env.local, keeping the old values, and --restore-env puts those back.

A draft that was never published is a 404 on localhost, and pushing after every edit is slow. With this running and the dev server pointed at it, the app renders the local story file on every reload, and nothing is pushed.

• It answers GET /v2/cdn/stories/<full slug> from the story file whose slug it is, read again on every request, in the folder bb story push recorded, or the default locale’s folder for a story with a parent_id. Every blok gets an _editable, so the page has data-blok-uid for measure and compare. A file it can’t read is a 500 that says why, and one line on stderr.
• Before a story’s first push, nothing checks its slug in the space: a local file can shadow a different story there until bb story push --plan refuses with slug-taken.
• It refuses to start on slug-mismatch, or two files with one slug (serve-conflict). One that turns up while it runs is answered with a 409, never with Storyblok’s story.
• Other slugs, such as settings, come once from the real Delivery API, as the draft, with the project’s public token, NEXT_PUBLIC_STORYBLOK_ACCESS_TOKEN, never the Management token. They’re cached in .backbase/cache/serve/; --offline uses only the cache. It never fetches from a URL on this machine.
• Safety. It listens on 127.0.0.1 only, answers 403 to any other Host header, so a web page can’t reach the drafts, refuses every method but GET and the GraphQL stub’s POST, never writes to Storyblok and logs no requests.
• A story from a local file carries story._backbase ({ "source": "local", "file", "servedAt" }), and the boilerplate shows its LOCAL DRAFT ribbon, which bb’s captures leave out. GET /_backbase/served?slug=<slug> says what answered a slug last.

--print-env prints the lines that point the dev server at it:

NEXT_PUBLIC_STORYBLOK_DELIVERY_API_URL=http://127.0.0.1:4100/v2
NEXT_PUBLIC_STORYBLOK_GRAPHQL_API_URL=http://127.0.0.1:4100/graphql
NEXT_PUBLIC_CONTENT_VERSION=draft

--write-env writes them to .env.local, keeping the lines they replace; --restore-env puts those back, and removes .env.local only when bb made it. Restart the dev server after either. Both warn when the shell or .env.development.local sets the same names, which Next.js reads first. The compose skill asks before it writes them.

It reads the story through the Management API, by id or full path, and never writes to the space. It checks what bb doctor --write checks, and refuses a folder (folder), a story the space doesn’t have (story-missing; a path needs its folders, such as en/summer-camps) and a slug that isn’t lowercase words joined by dashes (slug). It writes .backbase/stories/<slug>.json and <slug>.remote.json: the story’s id, slug and full path, updated_at, and a hash of the content and of each section, never a copy of it.

Without --force, it never replaces a local file that may hold work: one changed since the last pull or push (local-edits), one bb has no record of (local-file), or one recorded for another story (story-conflict). /backbase:edit always pulls first.

Read-only.

A section is a top-level blok in the page’s body, known by its sb-section name, or its _uid when it has none. :page is the page’s own fields and :order the sections’ order. The editor’s own additions to a design, such as its _uid, don’t count as a change; a cleared value does.

• data.push: your file against Storyblok now, what a push would change.
• data.remote: Storyblok now against your last pull or push, what someone else changed. changedHere marks a section your file changed too.
• data.conflicts: the sections in both, what a push would overwrite.

It writes a stamped story to the space through the Management API, as a draft, never published (ADR 0028), byte for byte from the file, so no size limit of an MCP call applies. Like Gate 2, it’s a plan you approve by its fingerprint, then the write of exactly that plan.

--plan writes nothing. It checks what bb doctor --write checks, then refuses, exit 1, when:

It creates a story when there’s no record, and updates the one <slug>.remote.json records, or --story <id> names. --story without a record has no push guard: the update replaces the whole content, so /backbase:edit never passes it. An update writes the content only, and the slug after bb story slug. The plan shows where it goes, create or update, whether the story is published (an update leaves the live page as it is until a person publishes), the sections it overwrites, its size, each new image, the fingerprint and the approval sentence, and saves it in .backbase/stories/push-plan.json.

--approved <fingerprint> plans again, and writes only when the fingerprint is the same (plan-changed otherwise), so an edit made in Storyblok after you approved refuses it too. Pass the same --overwrite-sections. It never sends publish, and has no flag for it: --publish is a usage error. A write may take 120 seconds, and a 429 or 5xx is retried four times. A create whose answer was lost is looked up by its path before it’s sent again; an update whose answer was lost is push-unconfirmed: run --plan to see. Then it updates the record.

The push guard

Before an update, --plan reads the story’s updated_at. When it moved since the record, and the push would change a section someone changed there, or undo their reorder, it refuses (remote-changed): Someone changed these sections in Storyblok since your pull. Pull again and make your change on what’s there now, or name each section: --overwrite-sections <keys>, as bb story diff prints them. Each overwrite is named in the plan, the fingerprint and the approval sentence. A save that changed none of your sections only warns.

In Claude Code, the plugin’s Bash hook blocks bb story push without --plan unless its --approved is the fingerprint in push-plan.json, given once, then asks you, naming the story, the space, the sections it overwrites and the approval sentence. It reads the plan in the folder the push runs in: the session’s, or one a plain cd <dir> && at the very start moves into. What it can’t follow for sure falls back to the session’s folder, and approved writes for two folders in one command are blocked. bb space sync and bb assets upload find their plans the same way. The token comes from your shell or the project’s .env, goes only over https to Storyblok’s Management API, and is masked in everything bb prints and writes.

For /backbase:edit: it adds a new image for one image field, --slot <uid>.<field>, from a local file, a Figma node’s downloaded image or a URL. It checks the slot first, and that the field is an asset field the catalog has, so an image is never uploaded for a field ops would refuse. It sniffs PNG, JPEG, WebP or GIF, never SVG, copies the file into .backbase/edits/<slug>/images/ (ignored), adds it to that edit’s images.json, and uploads nothing.

URLs come only from a public HTTPS host: never HTTP, localhost, or a loopback, private, shared, link-local, unique local, unspecified, multicast or reserved address, an IPv4 one inside IPv6 included. bb resolves the name itself, connects only to an address it checked, follows at most 5 redirects, each checked, and stops reading at 25 MB.

Then the same steps as compose: bb assets plan (into Edits / <story name>, reusing any image the project uploaded before), your yes, bb assets upload, and a setProp with its alt text. The push plan lists the new image.

It works offline. It sniffs each file’s format by its content (PNG, JPEG, WebP or GIF; Figma image fills are never SVG), skips any hash .backbase/assets.json already has, and plans the uploads into From Figma / <frame>. The space comes from storyblok.config, then .backbase/config.json, and is recorded for the write guard; stamps for another space block it. A video poster under 5,120 bytes, or transparent or of one colour, is refused as blank.

It saves .backbase/assets-plan.json with a fingerprint that binds the space, the images and their bytes, and an approvalSentence. Compose shows it, with which image goes where and what wasn’t found, in its one approval. A change needs a new plan and a new yes. Commit images.json and .backbase/assets.json; git ignores the downloads, the plans and .backbase/assets-upload.json.

After your yes, it uploads the plan through the Management API, with doctor’s token and region. The Bash hook blocks a missing or different --approved, also after leading flags such as bb --json assets upload, and asks you before a matching one runs. bb reuses an asset whose filename has the same hash, creates only the folders that are missing, signs each upload, sends it, finalizes it and records it.

It never sends the Management API token to S3, follows no redirects, and never replaces or deletes an asset. When it fails, what’s done stays recorded (data.uploaded): stop before the story, and run it again with the same approval, which skips them. Use data.assets[<imageHash>] as the image’s value, with your alt text.

Compose doesn’t need it: bb assets upload records each upload itself. It’s for an asset confirmed some other way.

A Wrap or a Create in the plan becomes a slot: a backbase-slot blok where the missing component goes, including bare section slots. In dev and drafts it’s a dashed box, fan-stack goes here · wrap of FanStack; in published production content it renders nothing.

• bb doctor --write and bb create install its schema, wrapper, map entry and placements, idempotently.
• Each slot carries its Figma node, figmaNode in bb story slots --json: its own layer, or its section’s node when the design read has no layer for it.
• Validation and the push plan list slots, and allow a draft push. Measure, compare and review leave a slot’s geometry out and badge it, until the component is built.

The component stage

/backbase:component, which compose and refine offer before their push, fills the slots:

1. bb check components --visibility: an existing wrapper is changed only after your yes;
2. bb component new for each slot, then Chaperone and TypeScript until green, and the catalog again;
3. bb space plan --components-only, then bb space sync --components-only --approved <fingerprint>, never --ssot. If you approve only part, it stops for a new plan;
4. each slot replaced through ops, then measured and reviewed;
5. one draft push, after its own yes.

Each Wrap was approved at Gate 1; each Create needs your yes again. Upstream is offered, and starts only if you ask.

bb story slot <section-or-blok-uid> --story <story.json> --as wrap --name fan-stack --export FanStack --note "Two refine rounds left the same structural height gap"

It replaces a composed section or blok with a slot in one ops envelope, records the Wrap or Create in the plan with the last two measured rounds as what was tried, and bb story ops undo takes both back. You decide every one: refine offers a slot only after two rounds leave a gap spacing can’t explain, and never makes one itself. Review the changed plan at Gate 1.

A Wrap is a component Backpack’s React has that Storyblok can’t ask for; a Create is new React from Backpack’s primitives. It writes either, in the project only:

bb component new fan-stack --wraps FanStack --in sb-flex-group
bb component new trip-builder --from Slider,SegmentedControls,Button

• A Wrap writes <Name>SB.tsx, mapping the blok’s fields to the export’s props, and <kebab>.sb.ts. A Create writes <Name>.tsx too.
• Both get Backpack’s design field, copied, never written by hand, the map entry in component-list.ts, and a place under each --in parent in backbase.placements.json, which one resolver applies when sb-mig syncs. Then it runs components:discover and the project’s Prettier.
• An optional yes-or-no prop that acts when unset becomes Automatic, On or Off.
• The wrapper passes its root’s display to getVisibilityClasses as originalDisplayProperty, so Show never turns a grid or flex root into a block.
• It refuses a name that starts sb- or ends -sb, and one Backpack or the project has already. Nothing goes to Storyblok until Gate 2.

The Chaperone preset

bb is a dev dependency of the project, pinned to one version, such as "@ef-global/backbase": "0.22.0", and .chaperone.json extends the preset it ships:

{
  "chaperoneVersion": "0.12.0",
  "extends": ["./node_modules/@ef-global/backbase/chaperone/backbase.json"]
}

chaperoneVersion goes in the project’s config: Chaperone rejects it in a preset. It’s a dev dependency, not npx, because Chaperone loads the preset from disk (without it, preset file not found), and so it’s offline, the same in CI, and the same version as the preset. bb doctor --write and bb create set it up: see project-chaperone. Run chaperone check --format ai after changing local components.

A local schema lives in src/components/<PascalCase>/<kebab>.sb.ts, with name: '<kebab>' and a <PascalCase>SB.tsx beside it. The folder’s case must match, on macOS too, and a name never starts with sb-. Every schema needs a map entry or an exception in component-map.exceptions.json, which must exist, and a parent placement.

The command rules give one result per component, such as schema-is-placeable:fan-stack, so a baseline counts per component. Fix findings rather than baselining them. Without bb installed, each says @ef-global/backbase isn't installed in this project: run npx @ef-global/backbase doctor --write. The preset also rejects rival UI kits, direct Radix imports, raw interactive HTML, Backpack deep imports and signs of copied source, though a rewritten copy gets past, so review still matters. See the preset’s README.

Where bb page compare gives a score, this gives exact pixels for every blok: what the frame says against what the page renders.

bb page measure --url https://localhost:3000/package-ils \
  --story .backbase/stories/package-ils.json

• The right page. It asks bb story serve what answered the page’s slug, and fails unless it was the --story file: served-from-storyblok, served-other-file, not-served or serve-unreachable. With --draft <full slug> it’s the other way round (served-from-local), the page opens through the preview route as compare’s does, and it writes under draft/.
• The capture. As compare’s, at the frame’s width, once the page settles, with what the page marks data-backbase-ignore hidden. It warns when the frame is exactly a breakpoint wide (768, 1024, 1240 or 1440px): a pixel narrower renders the layout below.
• Which layer is which blok. The map the scaffold recorded in the story’s report, bloks, else inferred from the copy. A section’s only root blok is the section’s own layer.
• The deltas, page minus frame, largest first: each gap between children, padding, width and height (labelled hug, fill or fixed), alignment, font size and line height. Under a pixel goes in within. Each section’s total is how far off it is in all.
• What no number fixes: overflow, a sizing mismatch (frame hug, page fill), and bloks with no layer. Sticky bars are measured where they rest.

measure.txt starts with the section heights, how many are within ±2px of the frame, and how many more within a token step (4px). --iteration writes into compare’s iteration: run bb page compare --iteration auto first.

Judging a try

--against <measure.json> judges this measure against a kept one, and --target <id> names the deltas the try aimed at. For each section:

• keep: every target moved toward the frame, and nothing else grew by more than a token step;
• partial: some targets moved, and nothing else grew;
• revert: none moved, or something else grew (grew).

A token step is the next value on the scale that sets the delta: Backpack’s spacing scale (0, 4, 8, 16, 24, 32, 48, 64, 128 in 4.11.0) for gaps and padding, its type ramp for type, the blok’s sizing field, or 4px, for sizes. A section is done when every delta and its height are within a step, and heightUnexplained when only the height isn’t. A fit that fell by more than --fit-drop sets look: true: look at the images. The fit never changes the decision.

Waiting for the page to settle

Measure, compare and review read a page only once it has settled: the document loaded, the fonts loaded, every image decoded, and the layout and the network still for 500ms. bb turns off smooth scrolling and transitions, makes lazy images eager and scrolls through the page first. Event streams, requests open for 5 seconds or more, and WebSockets don’t count, so hot reload doesn’t hold a page up.

It has 20 seconds, or --settle-timeout. Then it exits 1 with page-not-settled, naming what still moved or loaded, and writes no report. --allow-unsettled captures anyway, marked settled: false, and nothing is judged from it. It’s your call: the skills retry once, then tell you, and never pass it. A page that reloads or stops answering fails either way. See The page didn’t settle.

It’s optional: compose offers it, and never runs it on its own.

bb page compare --url https://localhost:3000/package-ils \
  --story .backbase/stories/package-ils.json

• Local or draft. With bb story serve running, --url shows the local story. --draft <full slug> opens Storyblok’s draft through the boilerplate’s preview route, with STORYBLOK_PREVIEW_SECRET from the shell, .env.local or .env. The secret is masked as *** everywhere bb prints or writes. A missing or too short secret is no-preview-secret; preview-refused, preview-elsewhere and preview-blocked say where the route stopped. Prefer the local route: the preview route may show Backpack’s StatusOverlay, which counts in the score.
• Which section is which. The scaffold’s report says which sections the story’s body holds; Global and Unsure aren’t on the page. Each body blok is found by data-blok-uid; when none match, by the order of main > *, or --selector, and the report says so. Shots are shots/<node-id>.png, or cropped from frame.png.
• The capture. One full-page screenshot at the frame’s width, once the page settles, each section cropped from it. Animations run to their end.
• The report, in .backbase/compare/<story>/: index.html, which opens offline from disk, and compare.json. It exits 0 when at least one section compares: a low score alone never fails.
• Iterations. --iteration auto writes a new numbered folder, never overwriting one, and latest/ points at the newest capture of every section. Each section gets a verdict against its last scored capture, better, same (within ±0.005) or worse, with the ops journal’s changes since. --section captures only those sections.

The score

fit is 0.4 × pixel similarity + 0.4 × edge agreement (how far edges moved) + 0.2 × height agreement, from 0 to 1, higher is better. Scores are a trend, not approval: fonts, browsers, moving content and white space all move them. Look at the images too.

It puts each section of the page beside its Figma shot, one image a section, for the agent to look at what numbers miss: a wrong variant, a colour, a missing gallery. Run it after bb page measure, with the same inputs and the same checks of where the page came from.

• Each section is found by data-blok-uid, scrolled into view, and captured a viewport at a time once it has settled in view, never in one full-page shot, which can re-lay out a carousel. Fixed and sticky bars outside it are hidden, and sticky ones inside it are pinned where the flow puts them. A failed capture is tried once more.
• A section that doesn’t settle, has no element, moves while it’s captured or has no Figma shot is not-captured, with its reason; the others are still reviewed. Run it again with --section. The whole review has 3 minutes, or --review-timeout.
• Each image has the frame on the left, the page on the right, and a header with the height, frame → page, and the measure’s count of deltas. There’s no score. Each run is a numbered folder in .backbase/review/<story>/, worst sections first, slots last.

The notes. For each section, the agent writes what differs in .backbase/review/<slug>/review.md, one line an item: - [<category>] <what's off, and where> — <outcome>. The categories are layout, spacing, typography, colour, imagery, component variant, overflow and content; the outcome open, fixed, design gap or content. --check-notes checks the file, exit 1 with review-notes errors. Compose, refine and edit all review before they push. A visible improvement may keep a change the measure would revert, but only written down, with the reason.

bb brings its own browser, so measuring a page changes neither your project nor anything else on your machine. It opens pages with the project’s own Playwright when its Chromium is installed, or else its own playwright-core, with Chromium in its own cache, backbase/ms-playwright in your user cache folder. Missing that, it exits 1: browser-missing names the folder and this command, and playwright-missing means bb’s install is incomplete. A Playwright on your PATH never counts.

This installs Chromium’s headless shell only: about 120 MB to download, 280 MB on disk. The skills ask you once first. An explicit PLAYWRIGHT_BROWSERS_PATH wins. bb never installs into Playwright’s shared cache, where an install deletes browsers other projects use, and never adds Playwright to the project.

It draws the run as one HTML page, beside the agent’s short answer in the chat. It reads only the project’s .backbase/, never writes to Storyblok or Figma, and fetches nothing: no script, and only the page’s own images. It uses the same plain words as the agent (packages/core/src/glossary.pure.ts).

bb report            # every view the run has so far, in .backbase/report.html
bb report plan       # one view, in .backbase/reports/plan.html
bb report all --open # and open it in your default browser

It draws every view whose files are there, and says why the rest aren’t. It fails only when none can be drawn (report-missing, report-unreadable), or, for one view, when its files aren’t there. A path that leads out of the project makes its view unreadable. --inline makes the page stand alone, with thumbnails, at most 4 MB of them. The same views are what bb mcp’s widgets show: they’re built in packages/core, from the run’s JSON.

Each reads the run's files as bb report does and shows its view as an MCP Apps widget, with a short card as text for a host without them. They only read: no Storyblok, no Figma, no file written. The plugin's .mcp.json starts it.

The plugin’s .mcp.json starts it as npx -y @ef-global/backbase@<the plugin's version> mcp --root ${CLAUDE_PROJECT_DIR}, so npx needs GitHub Packages in ~/.npmrc, and the first start downloads bb. Each tool is an MCP Apps tool: its _meta.ui.resourceUri links a ui://backbase/<view> page the app draws in a sandboxed frame.

Each takes project, the project’s folder (the folder bb mcp runs in when unset), and show_review takes slug, as bb report --slug does. Each returns:

• Text: the output contract’s short card, the decisions numbered with their recommended answers, then the report page’s path. It’s all an app without MCP Apps shows, the terminal included. Where the app says it draws MCP Apps, the skill’s message leaves out only the line the widget draws, and keeps what you approve: that nothing is written or published yet, what can be lost, closing the Settings story, the decisions, the approval sentence and the report link. The app only says it can draw the widget, not that it did.
• The view, in the result’s _meta, which never reaches the model: its HTML, with thumbnails inside, at most 2 MB.

A view that isn’t there yet is an error in the contract’s shape: “The plan can’t be shown yet. No .backbase/plan.json yet: Gate 1 writes it.”

Safety.

• The tools only read (readOnlyHint): no Storyblok, no Figma, no file written. Every secret in the env is masked out of the text and the view.
• A project outside the root (--root, or the folder it runs in) is refused, links followed, the same way whether or not it exists, so a call can’t probe the disk. It refuses to start with the disk’s root or the home folder as its root. Within a project, bb report’s own rule holds.
• The widget pages allow no network, in their Content-Security-Policy and _meta.ui.csp, and run one script, allowed by its SHA-256 hash, so a view can’t run one of its own. That script only talks to the app over postMessage: the handshake, the theme, its height, and a Show section N button that sends “show section N” in the chat. There’s no approve button: an approval is still the typed yes, so the write guard and the fingerprints are unchanged.

/backbase:upstream takes a component the project built to Backpack in two steps, each with your yes: an issue in ef-global/backpack, then a draft pull request (ADR 0029). This plans it against a fresh clone, writing nothing, and reads Backpack’s layout from the clone itself:

• Where the files go: a Wrap beside the component it wraps, such as src/components/FanStack/storyblok/FanStackSB.tsx; a Create in a folder of its own.
• The names get Backpack’s prefix: fan-stack becomes sb-fan-stack, shown as Fan Stack.
• The imports become Backpack’s own. What can’t, such as the project’s own modules, is listed under unresolved.
• What’s missing: what to add (presets, tests, a preview image, a story), edit (the story’s parameters.siteBuilder, the package export, and each parent’s whitelist, from backbase.placements.json) and generate (pnpm run components:discover).
• The rest: the branch, backbase-upstream-<kebab>, its base, the commit message in Backpack’s convention, and the story migration note.

It refuses already-in-backpack, reserved-name, not-a-component, wrapped-unknown, not-backpack and backpack-layout. --write writes into the clone only when it’s a git clone in the temp folder (clone-not-temp), on the plan’s branch (not-on-branch), never over other content (target-exists) or through a symlink out of it.

The two approvals. The agent files the issue only after your yes. It builds the branch, runs Backpack’s lint and tests, commits with its hooks on, and shows you the diff. After a second yes it pushes that branch, and no other, and opens a draft pull request. A yes to the issue never approves the pull request. It never merges, marks it ready, pushes to Backpack’s default or release branches, or runs Backpack’s release. The plugin’s Bash guard blocks merging or marking ready a pull request in ef-global/backpack, through gh, the REST API or GraphQL.

What the design needs and Site Builder doesn’t have goes to GCS, who make Backpack and Site Builder, as an issue in ef-global/backpack, and GCS decides (ADR 0030). This drafts one issue per request from the plan’s drafts. --issues is Backpack’s open issues, as gh issue list -R ef-global/backpack --state open --limit 1000 --json number,title,url,body,state,labels prints them: bb never calls GitHub itself. Each draft is:

• new: no open issue has it. The body is in .backbase/requests/<key>.issue.md;
• existing: an open issue has it, by its <!-- backbase-request: <key> --> marker or its title (Padding: 96px, never Padding: 960px). The draft is a comment adding this project’s evidence, so two projects ask once;
• filed: already recorded.

The approval. The agent shows you every draft, whole, and files only those you say yes to, as an issue or a comment, then records the link. Nothing else in Backpack: no labels created, no assignees, projects or milestones, and no other issue touched. A request you don’t approve stays a draft.

It writes **Filed:** <url> under the request in .backbase/requests/design-gaps.md, so no later run files it again. It refuses a link outside ef-global/backpack (not-a-request-link), an unknown key (request-unknown) and a project with no drafts (requests-missing); a request recorded already is already-recorded, unless --force.