@waron97/prbot 3.1.3 → 3.2.0

package/README.md

@@ -5,7 +5,7 @@ CLI tool for managing PRs, changelogs, and Odoo workflow XML files in the addons
 ## Install
 
 ```bash
-npm install -g .
+npm install -g @waron97/prbot
 ```
 
 ## Setup
@@ -36,7 +36,7 @@ Prompts for all required config values and writes them to `~/.config/prbot/confi
 | `DEVOPS_PROJECT`       | Azure DevOps project                                     |
 | `DEVOPS_REPO`          | Azure DevOps repository name                             |
 | `AUTOPR_TARGET_BRANCH` | Target branch for auto-created PRs (default: `15.0-dev`) |
-| `IMPORTEXPORT_URL`     | ImportExport API base URL                                 |
+| `IMPORTEXPORT_URL`     | ImportExport API base URL                                |
 
 ## Commands
 
@@ -208,23 +208,29 @@ agrippa init
 
 ### `agrippa clone`
 
-Clones all `from_code` phases for a selected workflow, or a single MFA, into the workspace. Writes files to disk and registers them in `agrippa.yaml`.
+Clones all `from_code` phases for a selected workflow, a single MFA, or a **process-builder wizard**, into the workspace. Writes files to disk and registers them in `agrippa.yaml`. With no flag, prompts for the object type (MFA / Phase / Process Builder).
+
+A wizard is downloaded and **decomposed** into editable files (`structure.yaml`, `process.yaml`, `scripts/`, `pages/`, manifest); see [`agrippa pb`](#agrippa-pb) and [`agrippa-pb.md`](agrippa-pb.md).
 
 ```bash
 agrippa clone
 agrippa clone --phase
 agrippa clone --mfa
 agrippa clone --phase --id 123 --path my-workflow/
+agrippa clone --pb                          # select a wizard
+agrippa clone --pb --name ml_review_billing --path my-wizard/
 ```
 
 Options:
 
-| Flag            | Description                                              |
-| --------------- | -------------------------------------------------------- |
-| `--phase`       | Clone a phase (select a workflow)                        |
-| `--mfa`         | Clone an MFA record                                      |
-| `--id <id>`     | Skip selection, clone by ID                              |
-| `--path <path>` | Destination path (base dir for phases, file path for MFA)|
+| Flag                   | Description                                                   |
+| ---------------------- | ------------------------------------------------------------- |
+| `--phase`              | Clone a phase (select a workflow)                             |
+| `--mfa`                | Clone an MFA record                                           |
+| `--pb`                 | Clone a process-builder wizard                                |
+| `--id <id>`            | Skip selection, clone by ID (phase/mfa)                       |
+| `--name <document_id>` | Skip selection, clone a wizard by `document_id` (with `--pb`) |
+| `--path <path>`        | Destination path (base dir for phases/wizard, file for MFA)   |
 
 ### `agrippa pull`
 
@@ -232,25 +238,34 @@ Fetches remote code for all tracked entries and shows what changed. Classifies e
 
 After pulling, also checks tracked workflows for newly added `from_code` phases and auto-clones any not yet present locally.
 
+Tracked **process-builder wizards** are also refreshed from upstream: the local project is re-decomposed from the latest payload (orphan script/page files pruned), with the same `fast-forward`/`conflict` classification (based on the wizard's upstream `updated_date` vs. the last pulled state). The current local state is backed up to `.backup/<timestamp>/<path>/local.json` first.
+
 ```bash
 agrippa pull
 ```
 
 ### `agrippa push`
 
-Pushes local file changes back to RIP. Backs up current remote code to `.backup/<timestamp>/` before overwriting. Same conflict detection as pull, with the concern inverted.
+Pushes local file changes back to RIP (phases/MFAs) and to the Process Builder API (wizards). Backs up current remote state to `.backup/<timestamp>/` before overwriting. Same conflict detection as pull, with the concern inverted.
+
+Pushing a wizard saves it as a **draft**; publish it so live consumers see the change with `--publish` (auto) or answer the prompt. Page edits (`pages/`) are saved independently of the whole-wizard save, mirroring the UI.
 
 ```bash
-agrippa push
+agrippa push                 # prompts whether to publish each pushed wizard
+agrippa push --publish       # auto-publish pushed wizards
+agrippa push --skip-publish  # never publish (no prompt)
 ```
 
 ### `agrippa diff [path]`
 
 Shows a diff between local files and remote code. Optionally filter to a specific file path.
 
+For process-builder wizards, diffs the whole project tree against what the workspace would look like if the wizard were decomposed fresh from upstream right now (`.backup/` and `preview.svg` are excluded as local-only artifacts).
+
 ```bash
 agrippa diff
 agrippa diff my-workflow/some-phase.py
+agrippa diff ml_review_billing      # a cloned wizard's directory
 ```
 
 ### `agrippa init-phase`
@@ -269,3 +284,27 @@ Removes entries from `agrippa.yaml` whose local files no longer exist on disk.
 agrippa repair
 ```
 
+### `agrippa pb`
+
+Local editing helpers for a **cloned process-builder wizard** (no network — they edit the decomposed files in place). Each operates on **one** wizard, resolved by `--pb <document_id>`, single-entry auto-select, or a fuzzy prompt.
+
+These commands exist mainly so an **AI agent** can add/remove/connect blocks without hand-editing the multi-thousand-line `structure.yaml`. Human users typically edit blocks in the UI instead. Full agent-facing guide (also usable as a workspace `CLAUDE.md`): [`agrippa-pb.md`](agrippa-pb.md).
+
+Newly added blocks get placeholder geometry. `pb format` re-lays-out the **whole** diagram (discarding any hand-tuned layout), so running it is a deliberate **human decision** — the alternative is positioning the new blocks by hand in the UI. Agents are expected to make structural edits but **not** to run `format` or to `pull`/`push`; a human reviews and syncs.
+
+| Command         | Purpose                                                                              |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `pb format`     | Re-lay-out the **entire** diagram (elkjs, left→right); overwrites existing layout    |
+| `pb add`        | Add a node (`--type`, `--name`, `--parent`); scaffolds script/page files             |
+| `pb rm`         | Remove a node (`--id`), its edges, and its script/page files                         |
+| `pb connect`    | Add a flow (`--from`, `--to`, `--condition`, `--default`); enforces the gateway rule |
+| `pb disconnect` | Remove a flow (`--id`, or `--from`/`--to`)                                           |
+| `pb ls`         | List nodes and edges with their ids (discover targets without reading the YAML)      |
+| `pb preview`    | Render the diagram to an SVG (`--out`) for a quick visual check                      |
+
+```bash
+agrippa pb ls --pb ml_review_billing
+agrippa pb add --type scriptTask --name "Check pod" --pb ml_review_billing
+agrippa pb connect --from ScriptTask_x --to ExclusiveGateway_y --pb ml_review_billing
+agrippa pb format --pb ml_review_billing
+```

package/agrippa-pb.md

@@ -0,0 +1,350 @@
+# Instructions for working with Phases, MFAs, and Process-Builder wizards
+
+You are my coding assistant developing MFAs, phases, and process-builder wizards for
+our Odoo CRM. Follow instructions precisely, without doing fixes or enhancements
+outside the scope of your instructions.
+
+This workspace is an **agrippa** workspace: a local checkout of Odoo code synced via
+the `agrippa` CLI. **You (the agent) never run `agrippa clone`, `agrippa pull`, or
+`agrippa push`** — those are human-only operations. You edit local files, and for
+wizards you also drive the `agrippa pb` editing commands (below). A human reviews and
+syncs.
+
+---
+
+## CRM structure
+
+### MFAs and phases
+
+The Odoo CRM uses a special module for exposing HTTP methods to the external world.
+The module name is RIP, which lets developers define "Model Function Access" records.
+Model Function Access (MFA) records contain Python code executed in `safe_eval`.
+
+Phases are `symple.triplet.phase` records tied to `helpdesk.ticket` objects.
+A helpdesk ticket has an associated `helpdesk.ticket.type`, which in turn has a
+`symple.workflow`. A workflow has a sequence of `symple.triplet.phase` that the ticket
+crosses in its lifecycle. There are many kinds of phases, but you only care about
+automatic phases that have Python code inside. In the directory structure, unless the
+current folder is named "mfa", each subdirectory is a workflow, and every Python file
+inside corresponds to a Python phase with code.
+
+For phases and MFAs you simply **edit the `.py` files** — there are no agrippa
+commands for you to run; a human clones/pulls/pushes them.
+
+### Workflow structure (`workflow.yml`)
+
+Each cloned workflow directory contains a `workflow.yml` next to its phase `.py`
+files. It is **auto-generated, read-only context** describing how the workflow is
+wired — the graph the editable phase files live inside. Read it to understand a
+workflow before editing a phase; **never edit it** (it is regenerated on every
+clone/pull and is not pushed anywhere). It does not contain phase Python code —
+that lives in the `.py` files.
+
+It holds:
+
+- `workflow` — identity + flags (`process_type`, `is_tiqv`, `start_phase`,
+  `code_excluded_phases`, and the `triplets` / ticket-type details that enter it).
+- `phases` — every phase as a graph node: `id`, `name`, `phase_code`,
+  `set_result_automatically`, `has_code_file` (true ⇒ an editable `.py` was cloned
+  for it), process/integration flags, `timeout`, `allowed_processes`,
+  `allowed_manual_phases`, and `results`.
+- `results` (per phase) — the **outgoing edges**: each `result` has a `next_phase`
+  plus, for `from_code` phases, the `code_values` the phase's Python must assign to
+  `result` to take that edge (and `triplet_details` for `from_triplet` phases).
+
+So to find "what value does this phase set to go to phase X", read `workflow.yml`:
+match the result whose `next_phase` is X and use its `code_values`.
+
+### Code inside phases and MFAs
+
+The following applies to both phases and MFAs.
+
+Some global utilities are made available inside the script, such as:
+
+- `json_dumps` (from `json.dumps`)
+- `json_loads` (from `json.loads`)
+- `datetime` (root-level import from datetime)
+- `dateutil` (root-level import from dateutil)
+- `request` (from `requests.request`)
+- `log` (logging method)
+- `format_exc` (from `traceback.format_exc`)
+- `first` (from `fields.first`)
+- `case_id` (phases only — the current `helpdesk.ticket`)
+
+The value of the `result` variable is used to construct the HTTP response.
+The `make_response` helper allows returning error states, e.g.
+`result = make_response((500, 500), "Custom error message")`.
+
+Some patterns not allowed in Odoo's `safe_eval`:
+
+- f-strings
+- imports
+- lambdas inside functions (`def` inside another function is fine)
+- doc strings (you cannot write to dunder fields)
+
+Notably unavailable:
+
+- `getattr`
+- `setattr`
+
+### Communication between phases
+
+A key entity is `symple.pb.process.data`. This model stores arbitrary data (most
+commonly JSON) in the `payload` field. It also has a `get_payload` method, which gives
+you the parsed JSON it contains. Phases, MFAs and other components commonly communicate
+via this model.
+
+The key-value store (kv_store) is a special process-data record accessible via
+`case_id.kv_store()`. It gives shorthand access to a process-data record unique to each
+case. It exposes 4 methods:
+
+- `get("key")`
+- `set("key", "value")`
+- `get_many("key", "key2")` → `a, b = case_id.sudo().kv_store().get_many("a, b")`
+- `set_many({"a": 1, "b": 2})`
+
+When possible, prefer the kv_store over manually creating and searching process-data
+records.
+
+---
+
+## Process-builder wizards
+
+A wizard is a BPMN process the CRM runs as a guided flow. Locally it has been
+**decomposed** into editable files. For wizards you are expected to **drive the
+`agrippa pb` commands** for structural changes — they hide BPMN id generation, the
+nested-YAML graph, dangling-edge cleanup, and the script/page/manifest bookkeeping you
+would otherwise get wrong by hand.
+
+> **You never run `agrippa push` or `agrippa pull`.** You only edit local files and run
+> the local, read/write `agrippa pb` subcommands. A human syncs and publishes.
+
+### Decomposed project layout
+
+```
+<wizard-dir>/
+  process.yaml      identity + top-level flags (envelope)
+  structure.yaml    THE graph: nodes hold their outgoing `edges` and nested
+                    `nodes` (for subProcess/transaction); inline geometry
+  scripts/NNNN_*.js one scriptTask body each (byte-exact)
+  pages/<formKey>.yml one userTask page object each
+  .agrippa-pb.json  manifest: scalars, namespaces, id↔file maps (do not hand-edit)
+```
+
+`structure.yaml` is large and nested. **Do not read it to find ids** — use `pb ls`.
+`agrippa-pb.json` is a massive json file. **Do not read it unless strictly required** — use `pb ls` and explore deconstructed files.
+
+A node looks like:
+
+```yaml
+- id: ScriptTask_0mmmti4
+  type: scriptTask
+  name: Init
+  script: scripts/0010_init.js      # ref to the body file
+  layout: { x: -462, y: 78, width: 84, height: 84 }
+  edges:                            # OUTGOING flows belong to the source node
+    - id: SequenceFlow_1lso8x0
+      target: ExclusiveGateway_1lghfov
+      waypoints: [[-378, 120], [-345, 120]]
+```
+
+Node types: `startEvent`, `endEvent`, `boundaryEvent`, `exclusiveGateway`,
+`scriptTask`, `serviceTask`, `userTask`, `subProcess`, `transaction`.
+
+### Your loop
+
+```
+agrippa pb ls            # discover node/edge ids
+agrippa pb add / rm / connect / disconnect / set-default   # change the graph
+# STOP. Do NOT format. Do NOT push. Report back to the human (see Formatting below).
+```
+
+Every `pb` command targets **one** wizard. **Always pass `--pb <document_id>`** so you
+never hit an interactive prompt.
+
+### Commands
+
+#### `pb ls` — discover ids
+
+```bash
+agrippa pb ls --pb <document_id>
+```
+
+Flat list of every node with its id, type, name, parent (if nested), and outgoing
+edges. **Start here** to find the ids you need. Example:
+
+```
+ScriptTask_0mmmti4  (scriptTask)  "Init"
+    → ExclusiveGateway_1lghfov  (SequenceFlow_1lso8x0)
+ExclusiveGateway_1lghfov  (exclusiveGateway)  "eg err"
+    → EndEvent_err  (SequenceFlow_a)  [default]
+    → ScriptTask_next  (SequenceFlow_b)  if ${isAlive}
+```
+
+`[default]` marks a gateway's default flow; `if …` shows a flow condition.
+
+#### `pb add` — add a node
+
+```bash
+agrippa pb add --type scriptTask --name "Check pod" --pb <document_id>
+agrippa pb add --type userTask   --name "Review"    --pb <document_id>
+agrippa pb add --type subProcess --name "Retry loop" --pb <document_id>
+agrippa pb add --type scriptTask --name "Inner" --parent SubProcess_x --pb <document_id>
+```
+
+Prints the new node id. Side effects, handled for you:
+
+- `scriptTask` → creates an **empty** `scripts/NNNN_<slug>.js`; edit that file for the body.
+- `userTask` → creates a **stub** `pages/<slug>.yml` + a manifest entry (no page content).
+- `subProcess`/`transaction` → empty container; add children with `--parent <its-id>`.
+
+The node is added **disconnected** with placeholder geometry. Connect it next.
+
+**Insert mode** — `--from <id> --to <id>` splices the new node into an existing flow
+instead of adding it disconnected:
+
+```bash
+agrippa pb add --type scriptTask --name "New" --from A --to End --pb <document_id>
+```
+
+Requires **exactly one** existing edge `A → End` already (errors if there's none, or
+more than one — ambiguous). That edge is kept (same id, name, condition, gateway
+`default` reference) and retargeted onto the new node; a second plain edge runs
+new-node → `End`. `--parent` is implied by `A`/`End`'s container, so don't pass both.
+`A`/`End` must be in the same container — it errors on boundary-crossing flows.
+
+#### `pb rm` — remove a node
+
+```bash
+agrippa pb rm --id ScriptTask_0mmmti4 --pb <document_id>
+```
+
+Removes the node (and, for a container, its children), **every edge pointing at it**
+(from anywhere in the graph), its own outgoing edges, and its script/page files +
+manifest entries. No dangling references left behind.
+
+#### `pb connect` — add a flow
+
+```bash
+# plain sequence
+agrippa pb connect --from ScriptTask_a --to ScriptTask_b --pb <document_id>
+
+# gateway branch with a condition
+agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_b \
+  --condition '${isAlive}' --pb <document_id>
+
+# the gateway's fallback branch
+agrippa pb connect --from ExclusiveGateway_g --to EndEvent_err \
+  --default --pb <document_id>
+```
+
+A flow's id is printed. Conditions default to `xsi:type="tFormalExpression"`
+(override with `--condition-type`). **Gateway rule** (enforced by Activiti, warned by
+this command): an `exclusiveGateway` with more than one outgoing flow must have
+**exactly one** `--default` flow, and **every other** outgoing flow must carry a
+`--condition`. Heed the `!` warnings `connect` prints.
+
+#### `pb disconnect` — remove a flow
+
+```bash
+agrippa pb disconnect --id SequenceFlow_1lso8x0 --pb <document_id>
+agrippa pb disconnect --from ScriptTask_a --to ScriptTask_b --pb <document_id>
+```
+
+#### `pb set-default` — change a gateway's default flow
+
+```bash
+agrippa pb set-default --id SequenceFlow_b --pb <document_id>
+agrippa pb set-default --from ExclusiveGateway_g --to EndEvent_err --pb <document_id>
+```
+
+Flips an **already-existing** flow to be its source gateway's `default`, by edge id or
+by `--from`/`--to` pair. Use this when a gateway already has a default and you want a
+different outgoing flow to become it — no need to `disconnect` and re-`connect` just to
+move the flag. The source must be an `exclusiveGateway`. Re-runs the gateway lint and
+prints any `!` warnings (e.g. a now-default flow that still carries a condition, or a
+non-default flow left without one).
+
+#### `pb preview` — visual check
+
+```bash
+agrippa pb preview --pb <document_id> --out /tmp/wizard.svg
+```
+
+Renders the current geometry to an SVG so a human can eyeball the result. Safe to run.
+Not byte-faithful to the real renderer — a sanity check only.
+
+### Formatting — a human decision, do NOT run it yourself
+
+`agrippa pb format` re-lays-out the **entire** wizard with an automatic algorithm.
+On an existing wizard this **discards the human's hand-tuned layout** and produces a
+drastically different diagram. That may or may not be acceptable — **only the human
+decides.**
+
+So when you have added/connected blocks, the new nodes are left with placeholder
+positions, and **you stop there**. Report to the human what you changed and that the
+new blocks need positioning, then let them choose one of:
+
+1. **Run `agrippa pb format`** themselves — accepts a full automatic re-layout of the
+   whole wizard (existing arrangement is lost), or
+2. **Position the new blocks by hand in the UI** after a human pushes the change —
+   preserving the existing layout.
+
+Never run `pb format` unless the human explicitly tells you to, with that trade-off
+understood.
+
+### What to edit by hand (vs. commands)
+
+Use the **commands** for graph structure (adding/removing nodes, wiring flows).
+Edit the **files directly** for content within an existing node:
+
+| Change | How |
+| --- | --- |
+| A scriptTask body | edit its `scripts/NNNN_*.js` file |
+| A userTask page | edit its `pages/<formKey>.yml` file |
+| A node's `name`, a flow's `condition`/`name`, serviceTask `fields`/`class` | edit `structure.yaml` for that node/edge |
+| Identity/flags | edit `process.yaml` |
+
+Never hand-edit `.agrippa-pb.json`, and never hand-assign `layout`/`waypoints`.
+
+### Recipes
+
+**Insert a block into an existing path** (`A → B` becomes `A → New → B`, anywhere in
+the graph, not just the end):
+
+```bash
+agrippa pb add --type scriptTask --name "New" --from A --to B --pb W   # → ScriptTask_new
+# then edit scripts/NNNN_new.js with the body, and report back (see Formatting)
+```
+
+Errors out instead of guessing if `A → B` doesn't have exactly one edge — fix the
+graph (`pb ls`) first if so.
+
+**Insert a decision branch** (gateway with two conditioned exits + a default):
+
+```bash
+agrippa pb add --type exclusiveGateway --name "alive?" --pb W   # → ExclusiveGateway_g
+agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_ok  --condition '${isAlive}' --pb W
+agrippa pb connect --from ExclusiveGateway_g --to EndEvent_err --default --pb W
+```
+
+**Add a subprocess with an inner step:**
+
+```bash
+agrippa pb add --type subProcess --name "Retry" --pb W          # → SubProcess_s
+agrippa pb add --type scriptTask --name "Attempt" --parent SubProcess_s --pb W
+```
+
+In every recipe: after the structural edits, **stop** and report — do not format, do
+not push.
+
+### Safety
+
+- `pb` commands are **local only** — nothing reaches upstream. Syncing
+  (`clone`/`pull`/`push`) and publishing are the human's job, never yours.
+- After every command the project is re-checked for recomposability; a broken edit is
+  reported with a `WARNING`.
+- When in doubt: `pb ls` to see the graph, make the structural change, `pb preview` to
+  show the human, then hand off.
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@waron97/prbot",
-    "version": "3.1.3",
+    "version": "3.2.0",
     "description": "",
     "main": "index.js",
     "scripts": {
@@ -14,26 +14,30 @@
         "@inquirer/search": "^2.0.1",
         "commander": "^14.0.2",
         "dotenv": "^17.2.3",
+        "elkjs": "^0.11.1",
         "eslint-plugin-es5": "^1.5.0",
+        "fast-xml-parser": "^5.9.2",
         "inquirer": "^13.4.2",
         "inquirer-search-list": "^1.2.6",
         "node-fetch": "^3.3.2",
         "omelette": "^0.4.17",
-        "prettier": "^3.5.3",
         "slugify": "^1.6.9",
         "yaml": "^2.9.0"
     },
     "devDependencies": {
         "@eslint/js": "^9.21.0",
+        "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
         "@types/node": "^25.0.10",
         "@typescript-eslint/parser": "^8.26.0",
         "eslint": "^9.21.0",
+        "prettier": "^3.8.4",
         "typescript": "^5.8.2",
         "typescript-eslint": "^8.26.0"
     },
     "files": [
         "src/",
-        "agrippa_typings/"
+        "agrippa_typings/",
+        "agrippa-pb.md"
     ],
     "keywords": [],
     "author": "",

package/src/agrippa/commands/clone.js

@@ -1,21 +1,23 @@
-import inquirer from 'inquirer';
-import select from '@inquirer/select';
 import search from '@inquirer/search';
-import { readConfig, writeConfig, loadEffectiveEnv } from '../lib/config.js';
-import { listWorkflows, getPhasesByWorkflow, listMfas } from '../lib/api.js';
+import select from '@inquirer/select';
+import inquirer from 'inquirer';
 import { getToken } from '../../lib/auth.js';
-import { computeChecksum } from '../lib/checksum.js';
-import { toSlug, defaultMfaPath, writeCodeFile } from '../lib/workspace.js';
 import { fuzzyMatch } from '../../lib/fuzzy.js';
+import { describeWorkflow, getPhasesByWorkflow, listMfas, listWorkflows } from '../lib/api.js';
+import { computeChecksum } from '../lib/checksum.js';
+import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
+import { defaultMfaPath, toSlug, writeCodeFile, writeWorkflowDoc } from '../lib/workspace.js';
+import { clonePb } from './clonePb.js';
 
 async function clone(opts) {
+    if (opts.pb) {
+        return clonePb(opts);
+    }
+
     const config = readConfig();
     loadEffectiveEnv(config);
 
-    const ripUrl = process.env.RIP_URL;
-    if (!ripUrl) throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
-
-    // Determine object type
+    // Determine object type (interactive prompt when no flag was passed)
     let objectType = opts.mfa ? 'mfa' : opts.phase ? 'phase' : null;
     if (!objectType) {
         objectType = await select({
@@ -23,9 +25,16 @@ async function clone(opts) {
             choices: [
                 { name: 'MFA', value: 'mfa' },
                 { name: 'Phase', value: 'phase' },
+                { name: 'Process Builder', value: 'pb' },
             ],
         });
     }
+    // Process-builder wizards have their own clone flow (PB_URL, recompose verify).
+    if (objectType === 'pb') return clonePb(opts);
+
+    const ripUrl = process.env.RIP_URL;
+    if (!ripUrl)
+        throw new Error('RIP_URL is not configured. Run `prbot init` or set it in agrippa.yaml.');
 
     console.log('Fetching records...');
     const token = await getToken();
@@ -52,9 +61,7 @@ async function clone(opts) {
         record = await search({
             message: `Select a ${objectType}:`,
             source: (input) => {
-                const filtered = input
-                    ? records.filter((r) => fuzzyMatch(r.name, input))
-                    : records;
+                const filtered = input ? records.filter((r) => fuzzyMatch(r.name, input)) : records;
                 return filtered.map((r) => ({
                     name: objectType === 'mfa' ? `${r.model_name} / ${r.name}` : r.name,
                     value: r,
@@ -102,6 +109,15 @@ async function clone(opts) {
             console.log(`  wrote ${filePath}`);
         }
 
+        // Drop the workflow graph alongside the phase files as read-only context.
+        try {
+            const structure = await describeWorkflow(token, ripUrl, record.id);
+            const docPath = writeWorkflowDoc(basePath, structure);
+            console.log(`  wrote ${docPath}`);
+        } catch (err) {
+            console.warn(`  could not fetch workflow structure: ${err.message}`);
+        }
+
         console.log(`Cloned ${phases.length} phase(s) to ${basePath}/`);
     } else {
         const defaultPath = defaultMfaPath(record.model_name, record.name);