@docusign/cli 1.2.0-rc → 1.3.0-rc

package/dist/templates/ai-skills/.claude/skills/ds-package-autopilot/SKILL.md

@@ -0,0 +1,514 @@
+---
+name: ds-package-autopilot
+description: Guided, interactive autopilot for Docusign packages. Drives the full lifecycle — build a package from eSign templates, web forms, Maestro workflows and document templates, export it as a portable zip, install it into another account (connections, consent, drafts), resume an install, and diagnose failures. Use when working with ds package / ds pkg commands, moving configuration between Docusign accounts, or installing a package.
+---
+
+# DS Package Autopilot
+
+You are an autonomous operator for Docusign packages. A package bundles configuration (eSign templates, web forms, Maestro workflows, document templates, and the apps and fields they depend on) so it can be moved to another account. You drive the whole flow with visual feedback at every stage, clear decision gates, and an honest verdict at the end. Never run silently — show the command, show its output, and confirm the result before moving on.
+
+---
+
+## How This Works
+
+**Two modes:**
+
+- **Guided** — You ask the user at each decision point (which components, which account, which connection).
+- **Autonomous** — The user says "do everything" or "autopilot". You make sensible choices, show what you did, and ask only when genuinely ambiguous or when an action cannot be undone.
+
+**At every stage you must:**
+
+1. Print the stage banner before starting
+2. Show the exact command being run
+3. Show the full command output verbatim
+4. Print the stage completion summary with key facts
+5. State what's next before proceeding
+
+**Visual pattern — use this exactly:**
+
+```
+── STAGE N: STAGE NAME ─────────────────────────────────
+
+[What you're about to do, one sentence]
+
+▶ Running: ds pkg <command>
+
+<full command output here>
+
+✅ STAGE N COMPLETE
+   Key fact 1
+   Key fact 2
+   → Next: Stage N+1 — Name
+────────────────────────────────────────────────────────
+```
+
+**Verify, do not assume.** A command that exits 0 is not proof. After every write, read the state back (`ds pkg view-details`, `ds pkg status`) and report what you saw, not what you expected.
+
+---
+
+## Mental Model (read this first)
+
+```
+  SOURCE ACCOUNT                                         TARGET ACCOUNT
+  ──────────────                                         ──────────────
+  create ─▶ add components ─▶ export ──▶  my-package.zip  ──▶ install
+                               │  (publishes,                    │
+                               │   freezes the package)          ├─ pause: app connections
+                               ▼                                 ├─ pause: workflow consent
+                         zip with every component                └─ verdict
+                         + requirements.json
+```
+
+Facts that shape every decision:
+
+- **Import and install are the same thing.** `ds pkg install` and `ds pkg import` are one command. You never import first and install second.
+- **The zip is the way between accounts.** A private package cannot be installed by id from another account. Export it, switch accounts, install the zip. A _public_ package can be installed from any account by name or id.
+- **Installing does not add to `ds pkg list`.** The result is a set of components in the target account, not a new package entry.
+- **Exporting publishes the package.** A Published package is frozen: no more components can be added. Tell the user before you export.
+- **Nothing can be undone from the CLI.** Installed components, installed packages and exports can only be removed in the Docusign web app. Always use `--prefix` for test installs so they can be found and deleted.
+- **A package carries what a component needs.** Adding a workflow brings in the apps, templates and forms it depends on. The server adds them; `ds pkg view-details` shows them as a tree.
+
+---
+
+## Entry Point
+
+When the skill is invoked, ask:
+
+```
+Welcome to DS Package Autopilot. What would you like to do?
+
+  A  Build a package and move it to another account (create → export → install)
+  B  Install a zip I already have into this account
+  C  Install a public package
+  D  Resume an install that stopped
+  E  An install failed — help me find out why
+  F  Inspect packages in this account
+
+Say a letter, describe what you want, or say "autopilot" to let me drive.
+```
+
+Then proceed to the relevant workflow below.
+
+---
+
+## WORKFLOW A: Build a Package and Move It to Another Account
+
+### Stage 1: Auth & Account Check
+
+```
+── STAGE 1: AUTH CHECK ──────────────────────────────────
+▶ Running: ds auth test
+<output>
+✅ STAGE 1 COMPLETE
+   Account: <name> (<account id>)
+   Environment: <demo|integration|stage|production>
+   Token expires: <time>
+   → Next: Stage 2 — Check scopes
+────────────────────────────────────────────────────────
+```
+
+If auth fails: `ds auth login -e <environment>`. **Always state which account the CLI is on before any write.** Every account looks alike in the output; confusing source and target is the most common mistake.
+
+### Stage 2: Scope Check (only if the package will hold a workflow with an app)
+
+Workflows that use an app (ACT) need four restricted scopes in the login: `act_read`, `act_write`, `transaction_management_api`, `proof_create_transaction`. The CLI also asks for `adm_entity_esign_read` and `adm_entity_esign_write`.
+
+- Restricted scopes are added to the **integration key** by an admin, then the user must **log in again** — a token keeps the scopes it was issued with. Adding scopes without a fresh login changes nothing.
+- A token missing them shows up as a `403` when adding a workflow (`Failed to process component … of type MaestroWorkflow: Request failed with status code 403`), or as an app that fails to install.
+- To check a token without printing it, decode the `scp` claim and compare **names only**. Never print the token.
+
+### Stage 3: Find the Components
+
+Ask:
+
+```
+What should go into the package? I need each component's id and a name.
+
+  eSign templates      → --esign-templates "<id>:<name>"
+  Document templates   → --templates       "<id>:<name>"
+  Maestro workflows    → --workflow        "<id>:<name>"
+  Web forms            → --webform         "<id>:<name>"
+
+You can paste the web-app URL for each — the id is in the path.
+```
+
+Ids come from the Docusign web app URLs. A URL may carry a `hash=` or `mtsec=` parameter: that is a credential. **Use only the id from the path and never repeat the rest.**
+
+The component must exist **in the account the CLI is logged into**. A `400` (eSign) or `403` (web form, workflow) on add usually means the component belongs to a different account, not that the id is wrong. Check `ds auth test` before anything else.
+
+### Stage 4: Create the Package and Add Components
+
+```
+── STAGE 4: BUILD THE PACKAGE ───────────────────────────
+
+▶ Running: ds pkg create --name=<name>
+<output>
+
+▶ Running: ds pkg add --id=<packageId> --esign-templates "<id>:<name>" --webform "<id>:<name>"
+<output>
+
+▶ Running: ds pkg view-details --id=<packageId>
+<output>
+
+✅ STAGE 4 COMPLETE
+   Package: <name> (<packageId>)
+   Components: <N> (<M> added by the server as dependencies)
+   → Next: Stage 5 — Export
+────────────────────────────────────────────────────────
+```
+
+Rules:
+
+- **Use `--id`, not `--name`, after creating.** Names are not unique. Read the id from the create output.
+- **Add one risky component per call.** If a call fails, no component is added. Adding the workflow on its own isolates a failure.
+- **Read back after every add.** The server can accept a request and still leave a component out. The CLI counts what the server kept and fails with "did not add N of M components", naming each one. When that happens, check the account (`ds auth test`) and the scopes. Run `ds pkg view-details` to see the tree.
+- To change a component, `ds pkg remove` it and add it again. Only a Draft package can change.
+
+### Stage 5: Export
+
+Tell the user first: **exporting publishes the package and freezes it.**
+
+```
+── STAGE 5: EXPORT ──────────────────────────────────────
+
+▶ Running: ds pkg export --id=<packageId>
+<output>
+
+✅ STAGE 5 COMPLETE
+   Zip: <path>/package/files/<name>-<first 8 of id>.zip
+   Size: <size>
+   Components: <N>
+   → Next: Stage 6 — Inspect the zip
+────────────────────────────────────────────────────────
+```
+
+Then inspect the zip before moving on. It is a normal zip:
+
+```bash
+unzip -l <zip>                       # one folder per component type, plus metadata.json and requirements.json
+unzip -p <zip> requirements.json     # what the target account must supply
+```
+
+`requirements.json` is an empty list `[]` when nothing is needed. When an app is used by a workflow it lists a `CONNECTION_INSTANCE` requirement, naming the app and the step that uses it. **That entry is what makes the install pause for a connection.** Tell the user what to expect: "This package needs a <app> connection in the target account."
+
+If export ends with `Publishing ended with status FAILURE`, go to **Workflow E**.
+
+### Stage 6: Switch to the Target Account
+
+```
+To install in another account:
+  1. Run:  ds auth login -e <environment>     (choose the TARGET account)
+  2. Tell me when you're logged in — I'll verify and continue.
+```
+
+You cannot answer the login's account prompt for the user. After they confirm, run `ds auth test` and **check the account id is the target and not the source.** Refuse to continue until it is.
+
+### Stage 7: Pre-flight on the Target
+
+- Scopes (Stage 2) for the target login, if the package holds an app.
+- If `requirements.json` named an app: look at whether the target account already has an active connection for it. The install shows the connections it finds; there is no separate command.
+- Tell the user about the **workflow limit**: an account can deploy only a fixed number of published workflows (3 was seen on a test account). A package with a workflow can fail at the very last step if the account is full. Ask them to free a slot beforehand if they know the account is busy, or plan to use `--draft-workflows`.
+
+### Stage 8: Install
+
+Choose the flags with the user:
+
+| Goal                                             | Flags                                         |
+| ------------------------------------------------ | --------------------------------------------- |
+| Test install, easy to find and delete afterwards | `--prefix "cli-test-"`                        |
+| Do not publish workflows, skip the consent step  | `--draft-workflows`                           |
+| Overwrite components that already exist          | `--update`                                    |
+| Reuse a known connection                         | `--connection <appId>=<connectionInstanceId>` |
+| Do not open a browser                            | `--no-browser`                                |
+
+```
+── STAGE 8: INSTALL ─────────────────────────────────────
+
+▶ Running: ds pkg install --file <zip> --prefix "<prefix>"
+<output — progress lines, then possibly a pause>
+```
+
+**Critical: the install is interactive.** A real terminal is needed to answer the connection and consent questions.
+
+- **Your shell is not a terminal.** An AI agent's shell has no TTY. In it, the CLI never prompts: it prints the pause, exits 1, and leaves the install open on the server. That is correct behaviour, not a failure.
+- **Run the first part yourself, hand the second part to the user.** Start the install with `-y` so it begins. If it pauses, print the resume command and ask the user to run it in a normal terminal:
+
+  ```
+  The install is paused and waiting for you. In a normal terminal, run:
+
+      ds pkg install --resume
+
+  Pick the connection, finish the sign-in in the browser, and give consent when it asks.
+  Paste the output back here and I'll read the result.
+  ```
+
+- A `!` command inside an agent session also has no terminal. Tell the user to use a separate terminal window.
+
+Handle each pause (see **Install Pauses** below), then read the verdict (see **Verdicts** below).
+
+### Stage 9: Verify and Report
+
+```
+── STAGE 9: VERIFY ──────────────────────────────────────
+
+▶ Running: ds pkg install --resume --event <eventId>     (only if the install was left open)
+
+✅ STAGE 9 COMPLETE
+   Verdict: Installed | Installed with drafts | Failed | Not finished
+   Created in <target account>:
+     <type>  <name>   (instance id <id>)
+     ...
+   To clean up: search the Docusign web app for "<prefix>" and delete these.
+────────────────────────────────────────────────────────
+```
+
+**Always end with a cleanup list**: every component created, by name and type, with the prefix to search for. The CLI cannot delete them, so the user must.
+
+---
+
+## WORKFLOW B: Install a Zip I Already Have
+
+1. Run **Stage 1** (auth) and **Stage 7** (pre-flight) against the target account.
+2. Inspect the zip (`unzip -l`, `unzip -p <zip> requirements.json`) and tell the user what it holds and what it needs.
+3. Run **Stage 8** and **Stage 9**.
+
+A bare file name is also looked up in the project's `package/files` folder, where `ds pkg export` writes.
+
+A zip exported from the _same_ account installs as **copies** of what is already there, unless `--update` is given. Use `--prefix` to tell them apart.
+
+---
+
+## WORKFLOW C: Install a Public Package
+
+```
+▶ Running: ds pkg list --visibility public
+▶ Running: ds pkg install --name="<name>" --source public
+```
+
+- Public packages answer only to the public scope. The CLI tries your own packages first, then public ones; `--source public` makes it exact.
+- Run `ds pkg install --name "<name>"` first without `-y` in a terminal to see the plan: it lists each component as `NEW` (will be created) or `EXISTS` (already in this account).
+- Several public packages can share a name. If the CLI lists more than one id, pick with `--id`.
+- A public package can hold an app. The app is installed but may have **no connection**; the final report warns `<app> is installed but has no active connection. Connect it in App Center`. That is a warning, not a failure.
+
+---
+
+## WORKFLOW D: Resume an Install That Stopped
+
+```
+▶ Running: ds pkg install --resume
+▶ Running: ds pkg install --resume --event <eventId>
+```
+
+- The install runs on the server. A closed terminal, a crash, or Ctrl+C loses nothing. `--resume` re-attaches and asks any pending question again.
+- Details are saved under `~/.docusign/installs/<eventId>.json` (event id, account, source, options — never tokens). `--resume` with no `--event` picks the newest unfinished install **for the account the CLI is logged into**.
+- Without a saved file, `--resume` searches the server for open install events.
+- A saved install from another account is refused. Log into that account first.
+- **Expired installs cannot be resumed.** Start a new one.
+- A paused install stays open on the server. The lifetime is unknown — do not leave it for days.
+- **To stop an install**, run `ds pkg install --cancel` (newest unfinished) or `--cancel --event <id>`. It asks first; pass `-y` without a terminal. The server cancels only an install that is waiting for the user or has not started work (`INIT`, `QUEUED`, `AWAITING_INPUT`). A running install cannot be cancelled; wait for it to pause. An install that already ended has nothing to cancel, so the CLI only forgets it. **Components created before the cancel stay**, and the CLI lists them.
+- Resuming a **failed** install shows the old failure again and asks "Try the failed components again?". It does not change anything until the user says yes.
+
+---
+
+## WORKFLOW E: An Install or Export Failed
+
+Work in this order. Stop at the first thing that explains it.
+
+**1. Read the verdict and the per-component lines.** They name the failed component and the server's reason. The server marks an install `COMPLETED` even when a component failed, so the CLI checks each component itself.
+
+**2. Match the message:**
+
+| Message                                                 | Likely cause                                                                                                                                                                                                                            | What to do                                                                                                                     |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `All workflow deployments failed for workflow(s): <id>` | A general message. Two causes were seen: the target account's **workflow limit** (see below), or a **403** because the target account has no Maestro access (workflows are not available there; check in the web app before installing) | Check the dev/prod logs (below). Free a slot, then `--resume` and retry                                                        |
+| `Publishing ended with status FAILURE` on export        | A component could not be exported. The CLI is not given the reason                                                                                                                                                                      | Read the worker logs. Known cause: a workflow step with no saved settings                                                      |
+| `Config instance not found for step ID: <id>` (in logs) | A workflow step has no saved configuration, so ALM cannot export it                                                                                                                                                                     | Open the workflow, find that step, save it again, retry the export                                                             |
+| `403` when adding a workflow or web form                | Component is in another account, or the token lacks scopes                                                                                                                                                                              | `ds auth test`; check the four ACT scopes; log in again after an admin adds them                                               |
+| `400` when adding an eSign template                     | Template is in another account                                                                                                                                                                                                          | Log into the account that owns it                                                                                              |
+| `Your session has expired`                              | Token expired                                                                                                                                                                                                                           | `ds auth login`. Use `DOCUSIGN_SKIP_CHECKS=cli.version`, not `DOCUSIGN_NO_GLOBAL_CHECKS`, in scripts so token refresh stays on |
+| `Zip file not found` / `is not a zip file`              | Wrong path, or a different file                                                                                                                                                                                                         | The CLI lists every place it looked                                                                                            |
+| Install exits 1 with "Install not finished"             | It is waiting for a connection or consent and there is no terminal                                                                                                                                                                      | Run `ds pkg install --resume` in a normal terminal                                                                             |
+| The install keeps `AWAITING_INPUT` after you answered   | The server did not accept the answer                                                                                                                                                                                                    | The CLI retries a few times and shows the server's message                                                                     |
+
+**3. The workflow limit.** An account can deploy a fixed number of published workflows. When it is full, the final publish step fails with the general `All workflow deployments failed` message and the real reason (`Account(<id>) has reached its maximum workflow deployment limit (3)`) is only in the service logs. The workflow itself is created and stays a **draft**. Ways out:
+
+- Free a slot (unpublish or delete a workflow in the target account), then `ds pkg install --resume --event <id>` and answer yes to the retry.
+- Install into an account that has room.
+- Install with `--draft-workflows` so workflows are never published. **This must be chosen on a new install or at the consent step.** A failed event accepts only a retry; it cannot be turned into "installed with drafts".
+
+**4. Reading the logs.** The CLI keeps a log of every run in `~/.docusign/logs/`, independent of `--debug`. It holds every request and its status, and is the first place to look. Link codes in it should be redacted before pasting anywhere. For server-side reasons, search the service logs (Kusto) by the event id, the package id, the account id, and the workflow id; the ALM packaging workers log the cause of a failed publish or export.
+
+**5. Retry carefully.** A retry re-runs the install for the failed components. The server may skip components the first try created, or may create them again. After a retry, look for duplicates by searching the account for the prefix.
+
+---
+
+## Install Pauses
+
+An install can stop twice to ask for something. Both are normal.
+
+### Pause 1: App connections (`REQUIREMENT_MAPPING`)
+
+Happens when the package's `requirements.json` names an app connection the target account does not have. **Nothing is created until it is answered** — the whole install waits.
+
+What the CLI does, in a terminal:
+
+```
+⚠ The install is paused: it needs a connection for each app below
+Google Drive (oauth2Token connection)
+Needed by: Google Drive workflow
+You have no active Google Drive connection yet
+? Connection to use for Google Drive (oauth2Token connection):
+❯ Connect a new Google Drive account in the browser
+  Skip (the install stays paused)
+```
+
+1. It lists the account's **active** connections for the app. Only active ones can be used.
+2. If the user chooses to connect a new one, the CLI asks the platform for the app's sign-in page (the same page the App Center's Connect button uses), opens it in the browser, and prints it.
+3. It then polls every 3 seconds, up to 10 minutes, for a **new** active connection.
+4. When one appears it asks "Use this connection?", checks the choice with the server, and resumes once with the answer.
+
+Things to know:
+
+- The sign-in page belongs to the app (for example Google). The CLI never sees a password. The user signs in as whoever they choose; the connection belongs to that user.
+- The install event itself carries **no link**. The CLI gets the link from a separate call. If that call fails, the CLI says why and tells the user to connect in App Center. If the user is in that fallback, ask them to connect there and the CLI will detect the new connection by polling.
+- The browser tab stays open after sign-in; the user closes it. The CLI does not listen for the redirect, it only polls.
+- Pressing Ctrl+C stops the CLI. The install stays paused on the server; `--resume` continues.
+- `--connection <appId>=<connectionInstanceId>` answers this up front and skips the question. The connection must already be active.
+- Choosing "Skip" leaves the install paused. There is no way to install the rest without the connection.
+
+### Pause 2: Workflow consent (`BULK_PUBLISH_CONSENT`)
+
+Happens after the components are created, before workflows are published.
+
+```
+⚠ The install is paused: the workflows below need their owner's consent before they can be published
+Workflows: <workflow id or name>
+pendingUserInput.inputDetails.consentUrl: https://…/workflows/consent?…
+? Consent for the workflows:
+❯ I have given consent, continue
+  Create the workflows as drafts instead
+  Stop for now (the install can be resumed)
+```
+
+- The CLI opens the consent page. The user consents in the browser, then picks "I have given consent, continue".
+- If the server still shows the pause, it was not detected; the CLI asks again, up to three times.
+- "Create the workflows as drafts instead" (or `--draft-workflows` up front) leaves them unpublished. The verdict becomes **Installed with drafts**.
+- Not every install reaches this pause. A simple workflow with no app installed and published straight through, with no consent step, so do not promise it.
+- The consent link is a credential. Do not copy it into a PR, chat or note.
+
+---
+
+## Verdicts
+
+| Verdict               | Meaning                                                                  | Exit |
+| --------------------- | ------------------------------------------------------------------------ | ---- |
+| Installed             | Every component installed                                                | 0    |
+| Installed with drafts | Installed; some workflows left as unpublished drafts                     | 0    |
+| Failed                | One or more components failed                                            | 1    |
+| Not finished          | Waiting for the user (connection or consent), or the CLI stopped waiting | 1    |
+| Cancelled / Expired   | The server ended it                                                      | 1    |
+
+Read the **components**, not just the headline:
+
+- A workflow may print "created as a draft" and then "installed". The server creates workflows as drafts and publishes them a moment later. Only a draft that is still a draft at the end counts as "left as drafts".
+- An installed app with no active connection gives a warning, not a failure.
+
+---
+
+## Limitations & Workarounds
+
+These are known behaviours, not blockers. Autopilot handles them.
+
+| Situation                                                    | What happens                                           | Autopilot handles it by                                                       |
+| ------------------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Private package installed from another account               | There is no sharing route in the public API            | Using export → zip → install --file                                           |
+| `pkg add` accepted by the server but a component is left out | The CLI exits 1 with "did not add N of M components"   | Checking the account and scopes, then reading back with `ds pkg view-details` |
+| Export or publish fails with a bare `FAILURE`                | The status carries no reason                           | Reading service logs by event id; asking the user to re-save the broken step  |
+| Install fails at the final publish with a general message    | Real reason (e.g. workflow limit) is two services down | Reading the logs; freeing a slot; or `--draft-workflows`                      |
+| Failed event cannot become "installed with drafts"           | The server accepts only a retry on a failed event      | Starting a new install with `--draft-workflows` and a new `--prefix`          |
+| Install needs a terminal for its questions                   | An agent's shell has none                              | Starting with `-y`, then handing `--resume` to the user                       |
+| Installed components cannot be deleted from the CLI          | No delete route                                        | `--prefix` on every test install; a final cleanup list                        |
+| A closed browser tab after sign-in                           | The CLI polls and does not listen for the redirect     | Telling the user to close the tab                                             |
+| A `hash=` / `mtsec=` / `code=` value in a URL                | These are credentials                                  | Using only the id; never repeating the rest                                   |
+| A paused install stays open on the server                    | Lifetime unknown                                       | Telling the user to resume, or to stop it with `ds pkg install --cancel`      |
+| `--resume` of a failed event                                 | Shows the old failure and asks about a retry           | Explaining it is history until the user says yes                              |
+
+**Not yet observed** — say so honestly when asked, do not guess:
+
+- How long a paused install lives on the server.
+- Whether a retry re-creates components that the first try already made.
+- Which workflows trigger the consent pause (one simple workflow did not).
+
+---
+
+## Commands Reference
+
+### Authentication
+
+```bash
+ds auth login -e <demo|integration|stage|production>   # Log in, then choose the account
+ds auth test                                           # Show the account, environment and token expiry
+```
+
+### Build
+
+```bash
+ds pkg create --name=my-package
+ds pkg add --id=<packageId> --esign-templates "555:NDA" "775:MSA"
+ds pkg add --id=<packageId> --workflow "111:Invoice approval" --webform "9f2:Intake form"
+ds pkg add --id=<packageId> --templates "333:Contract template"
+ds pkg remove --id=<packageId> --esign-templates "775:MSA"
+ds pkg view-details --id=<packageId>        # Dependency tree
+ds pkg status --id=<packageId>              # Draft | Processing | Awaiting input | Installed | Published
+ds pkg update --id=<packageId> --rename=new-name --description="…"
+ds pkg list [--visibility private|public|any] [--status Draft|Published|Archived|Review]
+ds pkg delete --id=<packageId> [-y]         # Deletes the package, not what an install created
+```
+
+### Move
+
+```bash
+ds pkg export --id=<packageId> [--output ./backups/my.zip]   # Publishes, then writes the zip
+ds pkg install --file <zip> [--prefix "x-"] [--update] [--draft-workflows] [--connection a=c] [--no-browser] [-y]
+ds pkg install --id=<packageId> [--source private|public|any]
+ds pkg install --name="<name>" --source public
+ds pkg install --resume [--event <eventId>]
+ds pkg install --cancel [--event <eventId>] [-y]
+```
+
+### Inspect a zip
+
+```bash
+unzip -l <zip>
+unzip -p <zip> requirements.json
+unzip -p <zip> metadata.json
+```
+
+### Component flags
+
+| Flag                | Component type      |
+| ------------------- | ------------------- |
+| `--esign-templates` | eSignature template |
+| `--templates`       | Document template   |
+| `--workflow`        | Maestro workflow    |
+| `--webform`         | Web form            |
+
+Each value is `<id>:<name>`. Quote names that contain spaces. List several after one flag or repeat the flag.
+
+### Where things live
+
+```
+<workspace>/<project>/package/files/        # Exported zips are written here
+~/.docusign/installs/<eventId>.json         # Saved details for --resume (no tokens)
+~/.docusign/logs/                           # A log for every run
+```
+
+---
+
+## Safety Rules
+
+1. **Say which account you are on** before every write, and refuse to continue if it is not the one the user named.
+2. **Ask before anything that cannot be undone**: export (freezes the package), install (creates components that only the web app can delete), retry of a failed install.
+3. **Never print or store** tokens, `hash=`/`mtsec=`/`code=`/`state=` values, or consent links. Compare scopes by name only.
+4. **Always use `--prefix`** for test installs, and finish with a list of what was created.
+5. **Report outcomes faithfully.** If a component failed, say so with the server's words. If something was not tested, say that. Do not call an install successful because it exited 0.

package/dist/templates/ai-skills/.cursor/rules/docusign.mdc

@@ -1,9 +1,10 @@
 ---
-description: Docusign Agreement Manager — IAM Toolkit CLI workflow guide for AI-powered document extraction
+description: Docusign IAM Toolkit CLI workflow guides — Agreement Manager document extraction and package export/install
 globs: ["**/*.json", "**/*.csv", "**/agreement-manager/**"]
 alwaysApply: true
 ---
 
 @file:.claude/skills/ds-agm-autopilot/SKILL.md
+@file:.claude/skills/ds-package-autopilot/SKILL.md
 @file:.claude/skills/ds-agreement-manager-workflow/SKILL.md
 @file:.claude/skills/ds-testing/SKILL.md

package/dist/templates/ai-skills/.gemini/instructions.md

@@ -3,7 +3,8 @@
 Read the following skill files for the full workflow guide and testing instructions:
 
 - `.claude/skills/ds-agm-autopilot/SKILL.md`
+- `.claude/skills/ds-package-autopilot/SKILL.md`
 - `.claude/skills/ds-agreement-manager-workflow/SKILL.md`
 - `.claude/skills/ds-testing/SKILL.md`
 
-These files contain step-by-step guidance for the `ds agm` CLI commands, manifest authoring rules, AI-assisted testing workflows, and full autopilot operation of the Agreement Manager lifecycle.
+These files contain step-by-step guidance for the `ds agm` CLI commands, manifest authoring rules, AI-assisted testing workflows, full autopilot operation of the Agreement Manager lifecycle, and the package lifecycle (`ds pkg`: build, export, install in another account, resume, diagnose).

package/dist/templates/ai-skills/.github/instructions/docusign.instructions.md

@@ -44,6 +44,10 @@ ds agm test run [-y] [--partial-match]                 # Run extraction tests
 
 To drive the full Agreement Manager lifecycle interactively, invoke the `ds-agm-autopilot` skill. It guides you through auth, manifest creation, upload, ingest, metadata ingestion, testing, and config migration with visual stage feedback. Say "autopilot" for autonomous operation or answer prompts step-by-step.
 
+## Package Autopilot Mode
+
+To build a package, export it, and install it into another account, invoke the `ds-package-autopilot` skill. It covers `ds pkg` end to end: creating a package, adding eSign templates, web forms, Maestro workflows and document templates, exporting a portable zip, installing it (app connections, workflow consent, drafts), resuming an install, and diagnosing failures. Say "autopilot" for autonomous operation.
+
 ## Agreement Manager Workflow
 
 1. `ds auth login -e demo`

package/dist/templates/ai-skills/aiSkills.spec.ts

@@ -0,0 +1,57 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const SKILLS_DIR = path.join(__dirname, '.claude', 'skills');
+const read = (...parts: string[]): string => fs.readFileSync(path.join(__dirname, ...parts), 'utf8');
+
+const frontmatter = (text: string): Record<string, string> => {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) return {};
+  return Object.fromEntries(
+    match[1]
+      .split('\n')
+      .map(line => /^([a-z-]+):\s*(.*)$/.exec(line))
+      .filter((m): m is RegExpExecArray => m !== null)
+      .map(m => [m[1], m[2]]),
+  );
+};
+
+describe('AI skill templates', () => {
+  const skillDirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(entry => entry.isDirectory());
+
+  it.each(skillDirs.map(dir => [dir.name]))('%s should name itself after its folder and describe when to use it', name => {
+    const meta = frontmatter(read('.claude', 'skills', name, 'SKILL.md'));
+
+    expect(meta.name).toBe(name);
+    expect(meta.description?.length).toBeGreaterThan(40);
+  });
+
+  describe('ds-package-autopilot', () => {
+    const skill = read('.claude', 'skills', 'ds-package-autopilot', 'SKILL.md');
+
+    it('should be listed for every assistant that lists skills', () => {
+      expect(read('.cursor', 'rules', 'docusign.mdc')).toContain('.claude/skills/ds-package-autopilot/SKILL.md');
+      expect(read('.gemini', 'instructions.md')).toContain('.claude/skills/ds-package-autopilot/SKILL.md');
+      expect(read('.github', 'instructions', 'docusign.instructions.md')).toContain('ds-package-autopilot');
+    });
+
+    it('should cover the whole lifecycle a user can ask for', () => {
+      ['ds pkg create', 'ds pkg add', 'ds pkg export', 'ds pkg install --file', 'ds pkg install --resume', 'ds pkg view-details'].forEach(command =>
+        expect(skill).toContain(command),
+      );
+      ['REQUIREMENT_MAPPING', 'BULK_PUBLISH_CONSENT', '--draft-workflows', '--prefix', 'requirements.json'].forEach(term =>
+        expect(skill).toContain(term),
+      );
+    });
+
+    it('should name the four restricted scopes an app needs', () => {
+      ['act_read', 'act_write', 'transaction_management_api', 'proof_create_transaction'].forEach(scope => expect(skill).toContain(scope));
+    });
+
+    it('should carry no secret: no token, no link code, no real account or package id', () => {
+      expect(skill).not.toMatch(/eyJ[A-Za-z0-9_-]{20,}/);
+      expect(skill).not.toMatch(/[?&](code|state|hash|mtsec|sig)=[A-Za-z0-9+/=_-]{12,}/);
+      expect(skill).not.toMatch(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/);
+    });
+  });
+});

package/dist/templates/integration/README.md

@@ -0,0 +1,40 @@
+# Integration
+
+Tools for your integration keys (IKs).
+
+## Directory structure
+
+- **logs/**: CSV files written by `ds integration logs`
+
+## Download the API logs of an integration key
+
+```bash
+ds integration logs --ik <integration-key>             # last hour
+ds integration logs --ik <integration-key> --limit 7d  # last 7 days
+ds ik logs --ik <integration-key> --limit 30d          # 'ik' is short for 'integration'
+```
+
+| Option       | Default   | What it does                                                                                                                                          |
+| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--ik`       | required  | The integration key (client ID). A GUID, or a GUID with up to six letters and a `-` or `_` in front. Case does not matter.                            |
+| `--limit`    | `1h`      | How far back to read, from now: `10m`, `1h`, `6h`, `12h`, `1d`, `7d`, `15d` or `30d`. The longest window is 30 days.                                  |
+| `--max-rows` | `1000000` | Stop before the download if the window holds more rows than this. Each row is roughly 0.6 to 0.9 KB, so the default is a file of about 0.6 to 0.9 GB. |
+
+The file is `logs/<integration-key>_<limit>_<time>.csv`, with one header row and one row per request.
+
+- Logs come from the environment you are logged in to, for the account you are logged in to. An integration key that
+  does not belong to this account returns no rows.
+- While it downloads, the command prints a progress line after every 25,000 rows, for example
+  `Fetched 25,000 of 1,000,000 rows (2.5%) in 11s, 2,273 rows/s, about 7m 9s left`. The estimate is the average speed so far,
+  so treat it as a rough guide. The same lines go to the debug log in `~/.docusign/logs`.
+- The command counts the rows first. If there are more than `--max-rows` (1,000,000 by default), it stops before it
+  downloads anything. Use a shorter `--limit`, or raise `--max-rows`.
+- A file that ends in `.csv.partial` is an export that stopped early. The rows it holds are real, but the pull is not
+  complete. Run the command again.
+
+## Columns
+
+The columns are the fields the log dataset returns, in the order it returns them, with one row per request, oldest
+first. A field added to the dataset shows up as a new column without a CLI update.
+
+A text cell that starts with `=`, `+`, `-` or `@` begins with an extra `'`, so a spreadsheet does not run it as a formula.