@transcend-io/cli 11.0.0 → 12.1.0

package/README.md

@@ -67,6 +67,7 @@ A command line interface that allows you to programatically interact with the Tr
   - [`transcend policy eval`](#transcend-policy-eval)
   - [`transcend policy init`](#transcend-policy-init)
   - [`transcend policy lint`](#transcend-policy-lint)
+  - [`transcend policy new`](#transcend-policy-new)
   - [`transcend policy bundles`](#transcend-policy-bundles)
   - [`transcend policy publish`](#transcend-policy-publish)
   - [`transcend policy test`](#transcend-policy-test)
@@ -2499,10 +2500,10 @@ FLAGS
      [--editor/--noEditor]  Merge target-scoped Deno editor settings and recommendations
      [--skill/--noSkill]    Install the canonical Custom Function coding-agent skill
      [--ci/--noCi]          Generate credential-free GitHub Actions checks
-     [--noInteractive]      Disable prompts and require every missing answer as a flag            [default = false]
-     [--dryRun]             Preview all changes without writing files                             [default = false]
+     [--noInteractive]      Disable prompts                                                       [default = false]
+     [--dryRun]             Preview changes without applying them                                 [default = false]
      [--yes]                Skip only the final plan confirmation                                 [default = false]
-     [--json]               Emit a stable JSON result and imply non-interactive output            [default = false]
+     [--json]               Emit stable JSON output and disable prompts                           [default = false]
   -h  --help                Print help information and exit
 
 ARGUMENTS
@@ -2549,13 +2550,13 @@ USAGE
 Adds a deterministic starter for one of two Custom Function types: General functions triggered by Rules Automation, or DSR functions triggered by a Workflow step and supporting data point resolvers, preflight checks, or both.
 
 FLAGS
-     [--manifest]       Path to an existing transcend-functions.yml
+     [--manifest]       Path to transcend-functions.yml; defaults inside the target directory
      [--name]           Customer-visible Custom Function display name
-     [--template]       Function type and generated handler shape                  [general|dsr-datapoint|dsr-enricher|dsr-both]
-     [--noInteractive]  Disable prompts and require every missing answer as a flag [default = false]
-     [--dryRun]         Preview all changes without writing files                  [default = false]
-     [--yes]            Skip only the final plan confirmation                      [default = false]
-     [--json]           Emit a stable JSON result and imply non-interactive output [default = false]
+     [--template]       Function type and generated handler shape                             [general|dsr-datapoint|dsr-enricher|dsr-both]
+     [--noInteractive]  Disable prompts                                                       [default = false]
+     [--dryRun]         Preview changes without applying them                                 [default = false]
+     [--yes]            Skip only the final plan confirmation                                 [default = false]
+     [--json]           Emit stable JSON output and disable prompts                           [default = false]
   -h  --help            Print help information and exit
 
 ARGUMENTS
@@ -2587,10 +2588,10 @@ Checks manifest semantics and published payload schemas, then uses Deno 2 withou
 
 FLAGS
      [--manifest]       Path to transcend-functions.yml; defaults inside the target directory
-     [--variables]      Comma-separated variables to template into the manifest               [default = ""]
-     [--fix]            Apply Deno formatting to manifest-referenced files                    [default = false]
-     [--noInteractive]  Disable the optional formatting confirmation                          [default = false]
-     [--json]           Emit a stable JSON result and imply non-interactive behavior          [default = false]
+     [--variables]      Comma-separated variables to template into the manifest, such as API_KEY:value [default = ""]
+     [--fix]            Apply Deno formatting to manifest-referenced files                             [default = false]
+     [--noInteractive]  Disable prompts                                                                [default = false]
+     [--json]           Emit stable JSON output and disable prompts                                    [default = false]
   -h  --help            Print help information and exit
 
 ARGUMENTS
@@ -2620,9 +2621,9 @@ Executes one self-contained manifest function against its configured test payloa
 FLAGS
      [--manifest]       Path to transcend-functions.yml; defaults inside the target directory
      [--function]       Exact Custom Function name or ID; prompts when omitted
-     [--variables]      Comma-separated manifest variables such as API_KEY:value              [default = ""]
-     [--noInteractive]  Disable function selection prompts                                    [default = false]
-     [--allowNetwork]   Permit real native fetch calls to manifest allowed-hosts              [default = false]
+     [--variables]      Comma-separated variables to template into the manifest, such as API_KEY:value [default = ""]
+     [--noInteractive]  Disable prompts                                                                [default = false]
+     [--allowNetwork]   Permit real native fetch calls to manifest allowed-hosts                       [default = false]
   -h  --help            Print help information and exit
 
 ARGUMENTS
@@ -2649,7 +2650,7 @@ Every `<<parameters.name>>` placeholder used by the selected function must be pr
 
 ```txt
 USAGE
-  transcend custom-functions push (--auth value) [--sombraAuth value] [--transcendUrl value] [--file value] [--variables value] [--dryRun] [--promote] [--force] [--skipTests] [--updateManifest] [--sombraId value]
+  transcend custom-functions push (--auth value) [--sombraAuth value] [--transcendUrl value] [--manifest value] [--variables value] [--dryRun] [--json] [--promote] [--force] [--skipTests] [--updateManifest] [--sombraId value] [<directory>]
   transcend custom-functions push --help
 
 Sync custom function source code from your repository to Transcend.
@@ -2675,19 +2676,25 @@ FLAGS
       --auth                  The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Manage Data Map"
      [--sombraAuth]           The Sombra internal key, use for additional authentication when self-hosting Sombra
      [--transcendUrl]         URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported.                [default = https://api.transcend.io]
-     [--file]                 Path to the custom functions manifest YAML file                                                                                                                                                                   [default = ./transcend-functions.yml]
-     [--variables]            Variables to template into the manifest file (e.g. secret env values). Comma-separated list of key:value pairs.                                                                                                   [default = ""]
-     [--dryRun]               When true, report what would change without pushing anything                                                                                                                                                      [default = false]
+     [--manifest]             Path to transcend-functions.yml; defaults inside the target directory
+     [--variables]            Comma-separated variables to template into the manifest, such as API_KEY:value                                                                                                                                    [default = ""]
+     [--dryRun]               Preview changes without applying them                                                                                                                                                                             [default = false]
+     [--json]                 Emit stable JSON output and disable prompts                                                                                                                                                                       [default = false]
      [--promote/--noPromote]  When true, promote new revisions to active. Set to false to leave new revisions as drafts for review in the dashboard.                                                                                            [default = true]
      [--force]                Push a new revision even when no changes are detected. Useful when only environment variable values changed, which cannot be diffed.                                                                              [default = false]
      [--skipTests]            Skip test runs entirely, pushing functions without executing their test-payload files. Tests also do not run on --dryRun (nothing is signed on dry runs).                                                         [default = false]
      [--updateManifest]       After pushing, write the assigned custom function IDs back into the manifest file so future pushes match by ID instead of by name. Comments and <<parameters.x>> placeholders are preserved.                      [default = false]
      [--sombraId]             Default Sombra gateway for functions whose manifest entry (or existing function) does not pin one. Each function is signed against the gateway it belongs to. Defaults to the primary Sombra of the organization.
   -h  --help                  Print help information and exit
+
+ARGUMENTS
+  [directory]  Custom Function project directory [default = transcend/custom-functions]
 ```
 
 #### Manifest file
 
+By default, `push` reads `transcend-functions.yml` from the `transcend/custom-functions` project directory. Pass another project directory positionally, or use `--manifest` to select a specific manifest file. Use `--json` in automation to emit one structured result containing the manifest path, per-function outcomes, and aggregate counts.
+
 The manifest maps custom function names to source files in your repository:
 
 ```yaml
@@ -2788,7 +2795,7 @@ DSR functions have two entry points — the default export (`DATA_POINT`) and th
 
 #### Examples
 
-**Push all custom functions defined in ./transcend-functions.yml**
+**Push all custom functions defined in transcend/custom-functions/transcend-functions.yml**
 
 ```sh
 transcend custom-functions push --auth="$TRANSCEND_API_KEY"
@@ -2805,7 +2812,7 @@ transcend custom-functions push --auth="$TRANSCEND_API_KEY" --dryRun
 ```sh
 transcend custom-functions push \
   --auth="$TRANSCEND_API_KEY" \
-  --file=./transcend/functions.yml \
+  --manifest=./transcend/functions.yml \
   --variables=CRM_API_KEY:example-secret-value
 ```
 
@@ -2849,7 +2856,7 @@ transcend custom-functions push --auth="$TRANSCEND_API_KEY" --transcendUrl=https
 
 ```txt
 USAGE
-  transcend custom-functions list (--auth value) [--transcendUrl value]
+  transcend custom-functions list (--auth value) [--transcendUrl value] [--json]
   transcend custom-functions list --help
 
 List all custom functions in the organization along with their lifecycle state, active version, and any pending draft version.
@@ -2857,9 +2864,12 @@ List all custom functions in the organization along with their lifecycle state,
 FLAGS
       --auth           The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Data Map"
      [--transcendUrl]  URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
+     [--json]          Emit stable JSON output and disable prompts                                                                                                                                                        [default = false]
   -h  --help           Print help information and exit
 ```
 
+Use `--json` in automation to emit safe structured metadata for every Custom Function. Signed code and context tokens are never included in the JSON output.
+
 ### `transcend inventory pull`
 
 ```txt
@@ -4132,20 +4142,20 @@ transcend migration sync-ot --source=file --file=./oneTrustAssessments.json --tr
 
 ```txt
 USAGE
-  transcend policy activate (--bundle-name value) [--version value] (--auth value) [--transcend-url value] [--dry-run] [--json] [--debug]
+  transcend policy activate (--remote-bundle-name value) [--version value] (--auth value) [--transcend-url value] [--dry-run] [--json] [--debug]
   transcend policy activate --help
 
 Calls the Policy Engine activate endpoint to make an uploaded version live. Addressed by bundle name (resolved to the parent bundle UUID internally). When --version is omitted, activates the latest uploaded version by createdAt. Requires a Transcend API key with Activate Policy scope.
 
 FLAGS
-      --bundle-name       Logical policy bundle name (the same string used in publish/bundles); resolved to the parent bundle UUID internally
-     [--version]          Caller-supplied version label to activate; defaults to the latest uploaded version by createdAt
-      --auth              The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
-     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--dry-run]          Validate activation without flipping the active version                                                                                                                                            [default = false]
-     [--json]             Print the raw JSON API response                                                                                                                                                                    [default = false]
-     [--debug/--noDebug]  Include technical error details (underlying API message and stack trace) when a command fails
-  -h  --help              Print help information and exit
+      --remote-bundle-name  Remote Policy Engine bundle name (not the local folder or --name root)
+     [--version]            Caller-supplied version label to activate; defaults to the latest uploaded version by createdAt
+      --auth                The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
+     [--transcend-url]      URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcend-url may be omitted if it is exported. [default = https://api.transcend.io]
+     [--dry-run]            Validate activation without flipping the active version                                                                                                                                             [default = false]
+     [--json]               Print the raw JSON API response                                                                                                                                                                     [default = false]
+     [--debug/--noDebug]    Include technical error details (underlying API message and stack trace) when a command fails
+  -h  --help                Print help information and exit
 ```
 
 #### Examples
@@ -4153,25 +4163,25 @@ FLAGS
 **Activate the latest uploaded version for a bundle**
 
 ```sh
-transcend policy activate --bundle-name=main --auth="$TRANSCEND_API_KEY"
+transcend policy activate --remote-bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Activate a specific version label by bundle name**
 
 ```sh
-transcend policy activate --version=abc123 --bundle-name=main --auth="$TRANSCEND_API_KEY"
+transcend policy activate --version=abc123 --remote-bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Validate activation without flipping the active version**
 
 ```sh
-transcend policy activate --version=abc123 --bundle-name=main --auth="$TRANSCEND_API_KEY" --dry-run
+transcend policy activate --version=abc123 --remote-bundle-name=main --auth="$TRANSCEND_API_KEY" --dry-run
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy activate --bundle-name=main
+transcend policy activate --remote-bundle-name=main
 ```
 
 Requires the **Activate Policy** scope on your API key.
@@ -4180,18 +4190,18 @@ Requires the **Activate Policy** scope on your API key.
 
 ```txt
 USAGE
-  transcend policy deactivate (--bundle-name value) (--auth value) [--transcend-url value] [--json] [--debug]
+  transcend policy deactivate (--remote-bundle-name value) (--auth value) [--transcend-url value] [--json] [--debug]
   transcend policy deactivate --help
 
 Calls the Policy Engine deactivate endpoint to take the currently active version of a bundle offline, clearing its active version pointer. Addressed by bundle name (resolved to the parent bundle UUID internally). Requires a Transcend API key with Activate Policy scope.
 
 FLAGS
-      --bundle-name       Logical policy bundle name (the same string used in publish/bundles); resolved to the parent bundle UUID internally
-      --auth              The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
-     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--json]             Print the raw JSON API response                                                                                                                                                                    [default = false]
-     [--debug/--noDebug]  Include technical error details (underlying API message and stack trace) when a command fails
-  -h  --help              Print help information and exit
+      --remote-bundle-name  Remote Policy Engine bundle name (not the local folder or --name root)
+      --auth                The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Activate Policy"
+     [--transcend-url]      URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcend-url may be omitted if it is exported. [default = https://api.transcend.io]
+     [--json]               Print the raw JSON API response                                                                                                                                                                     [default = false]
+     [--debug/--noDebug]    Include technical error details (underlying API message and stack trace) when a command fails
+  -h  --help                Print help information and exit
 ```
 
 #### Examples
@@ -4199,19 +4209,19 @@ FLAGS
 **Deactivate the active version of a bundle by name**
 
 ```sh
-transcend policy deactivate --bundle-name=main --auth="$TRANSCEND_API_KEY"
+transcend policy deactivate --remote-bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Print the raw JSON response**
 
 ```sh
-transcend policy deactivate --bundle-name=main --auth="$TRANSCEND_API_KEY" --json
+transcend policy deactivate --remote-bundle-name=main --auth="$TRANSCEND_API_KEY" --json
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy deactivate --bundle-name=main
+transcend policy deactivate --remote-bundle-name=main
 ```
 
 Requires the **Activate Policy** scope on your API key.
@@ -4220,20 +4230,20 @@ Requires the **Activate Policy** scope on your API key.
 
 ```txt
 USAGE
-  transcend policy download (--bundle-name value) [--version value] [--output value] (--auth value) [--transcend-url value] [--json] [--debug]
+  transcend policy download (--remote-bundle-name value) [--version value] [--output value] (--auth value) [--transcend-url value] [--json] [--debug]
   transcend policy download --help
 
 Resolves a bundle name and optional version label, fetches a short-lived presigned URL from the Policy Engine API, and downloads the compiled OPA bundle tarball (.tar.gz) to disk. When --version is omitted, downloads the currently active version (errors if none is active). With --json, prints metadata and the presigned URL without writing a file. Requires a Transcend API key with View Policy scope.
 
 FLAGS
-      --bundle-name       Tenant-unique policy bundle name
-     [--version]          Caller-supplied version label to download; defaults to the bundle's currently active version
-     [--output]           Destination file path for the compiled .tar.gz bundle (defaults to {bundleName}-{version}.tar.gz)
-      --auth              The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
-     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--json]             Print version metadata and the presigned download URL as JSON without writing a file                                                                                                               [default = false]
-     [--debug/--noDebug]  Include technical error details (underlying API message and stack trace) when a command fails
-  -h  --help              Print help information and exit
+      --remote-bundle-name  Remote Policy Engine bundle name (not the local folder or --name root)
+     [--version]            Caller-supplied version label to download; defaults to the bundle's currently active version
+     [--output]             Destination file path for the compiled .tar.gz bundle (defaults to {bundleName}-{version}.tar.gz)
+      --auth                The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
+     [--transcend-url]      URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcend-url may be omitted if it is exported. [default = https://api.transcend.io]
+     [--json]               Print version metadata and the presigned download URL as JSON without writing a file                                                                                                                [default = false]
+     [--debug/--noDebug]    Include technical error details (underlying API message and stack trace) when a command fails
+  -h  --help                Print help information and exit
 ```
 
 #### Examples
@@ -4241,20 +4251,20 @@ FLAGS
 **Download the currently active version of a policy bundle**
 
 ```sh
-transcend policy download --bundle-name=main --auth="$TRANSCEND_API_KEY"
+transcend policy download --remote-bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Download a specific compiled policy bundle version to the default path**
 
 ```sh
-transcend policy download --bundle-name=main --version=2026-06-25 --auth="$TRANSCEND_API_KEY"
+transcend policy download --remote-bundle-name=main --version=2026-06-25 --auth="$TRANSCEND_API_KEY"
 ```
 
 **Download to an explicit output path**
 
 ```sh
 transcend policy download \
-  --bundle-name=main \
+  --remote-bundle-name=main \
   --version=2026-06-25 \
   --auth="$TRANSCEND_API_KEY" \
   --output=./bundles/main-2026-06-25.tar.gz
@@ -4263,13 +4273,13 @@ transcend policy download \
 **Print version metadata and the presigned URL as JSON without writing a file**
 
 ```sh
-transcend policy download --bundle-name=main --version=2026-06-25 --auth="$TRANSCEND_API_KEY" --json
+transcend policy download --remote-bundle-name=main --version=2026-06-25 --auth="$TRANSCEND_API_KEY" --json
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy download --bundle-name=main
+transcend policy download --remote-bundle-name=main
 ```
 
 Requires the **View Policy** scope on your API key.
@@ -4280,58 +4290,91 @@ The downloaded artifact is a compiled OPA bundle tarball (`.tar.gz`), not a `.zi
 
 ```txt
 USAGE
-  transcend policy eval (--pkg value) (--input value) [--bundle value]
+  transcend policy eval (--package value) [--input value] [--stdin-input] [--format pretty|json|values|bindings|source|raw|discard] [--schema value] [--explain off|full|notes|fails|debug] [--metrics] [--instrument] [--profile] [--timeout value] [--var-values] [--show-builtin-errors] <bundle>
   transcend policy eval --help
 
-Wraps `opa eval` for local policy debugging. Requires the `opa` CLI on PATH. No Transcend API key is needed.
+Wraps `opa eval` for local policy debugging against one bundle directory. Always loads the directory as a bundle (`-b`) and ignores local `*_test.rego` files (same as lint/publish — tests are not shipped to Evaluate). Provide input via `--input` or `--stdin-input` (exactly one). Pass-through flags cover format, schema, explain, metrics, instrument, profile, timeout, var-values, and show-builtin-errors. `-b` and `--ignore` stay owned by the CLI. Exit-on-result flags like OPA `--fail` are omitted: production Evaluate uses the Data API (policy deny is a successful evaluation; missing result is an engine failure), so process exit-on-result is not Evaluate parity. Requires an explicit directory containing a `.manifest`, and the `opa` CLI on PATH. No Transcend API key is needed.
 
 FLAGS
-      --pkg      OPA package or query to evaluate (e.g. data.transcend.decision)
-      --input    Path to a JSON envelope input file
-     [--bundle]  Optional local policy bundle directory
-  -h  --help     Print help information and exit
+      --package               OPA query path to evaluate (e.g. data.example.result)
+     [--input]                Path to a JSON envelope input file (mutually exclusive with --stdin-input)
+     [--stdin-input]          Read the input document from stdin (opa eval --stdin-input)                [default = false]
+     [--format]               Output format (opa eval --format)                                          [pretty|json|values|bindings|source|raw|discard, default = pretty]
+     [--schema]               JSON Schema file or directory for input type-checking (opa eval --schema)
+     [--explain]              Explanation mode (opa eval --explain)                                      [off|full|notes|fails|debug]
+     [--metrics]              Report evaluation metrics (opa eval --metrics)                             [default = false]
+     [--instrument]           Enable instrumentation; implies --metrics (opa eval --instrument)          [default = false]
+     [--profile]              Enable performance profiling (opa eval --profile)                          [default = false]
+     [--timeout]              Evaluation timeout duration, e.g. 5s (opa eval --timeout)
+     [--var-values]           Show variable values with --explain (opa eval --var-values)                [default = false]
+     [--show-builtin-errors]  Collect and report built-in errors (opa eval --show-builtin-errors)        [default = false]
+  -h  --help                  Print help information and exit
+
+ARGUMENTS
+  bundle  Local policy bundle directory containing a .manifest
 ```
 
 #### Examples
 
-**Evaluate a decision query with a local envelope**
+**Evaluate a generic decision query with a local envelope**
+
+```sh
+transcend policy eval transcend/policy/example-bundle \
+  --package=data.example.result \
+  --input=transcend/policy/example-bundle/input.json
+```
+
+**Simulate the Permissions API (query + envelope + input schema)**
 
 ```sh
-transcend policy eval --pkg=data.transcend.decision --input=./fixtures/envelope.json --bundle=./policies
+transcend policy eval transcend/policy/permissions-bundle \
+  --package=data.permissions.purposes \
+  --input=transcend/policy/permissions-bundle/input.json \
+  --schema=transcend/policy/permissions-bundle/input.schema.json
 ```
 
+**Pipe an envelope on stdin**
+
+```sh
+cat transcend/policy/example-bundle/input.json | transcend policy eval transcend/policy/example-bundle --package=data.example.result --stdin-input
+```
+
+The `<bundle>` positional is required (one local publish directory with a `.manifest` per
+invocation). Pass `--schema` with the bundle's `input.schema.json` when you want OPA to
+type-check `input` (e.g. `transcend/policy/permissions-bundle/input.schema.json`).
+
 ### `transcend policy init`
 
 ```txt
 USAGE
-  transcend policy init [--editor] [--skill] [--ci] [--noInteractive] [--dryRun] [--yes] [--json] [<directory>]
+  transcend policy init [--editor] [--skill] [--ci] [--noInteractive] [--dryRun] [--yes] [--json] [<workspace>]
   transcend policy init --help
 
-Probes OPA and Regal, previews one safe transactional plan, and creates a publishable fail-closed Rego v1 starter only in an empty target. Optional editor, Agent Skill, and validation-only CI setup preserve repository customization. No Transcend credentials are needed.
+Probes OPA and Regal, previews one safe transactional plan, and creates an empty multi-bundle workspace with shared Regal config and README. Add bundles with `transcend policy new`. Optional editor, Agent Skill, and validation-only CI setup preserve repository customization. No Transcend credentials are needed.
 
 FLAGS
      [--editor/--noEditor]  Merge strict target-scoped VS Code settings, extensions, and lint task
      [--skill/--noSkill]    Install the canonical Policy Engine coding-agent skill
      [--ci/--noCi]          Generate credential-free validation-only GitHub Actions
      [--noInteractive]      Disable prompts and enable optional setup only through explicit flags  [default = false]
-     [--dryRun]             Preview all changes without writing files                              [default = false]
+     [--dryRun]             Preview changes without applying them                                  [default = false]
      [--yes]                Skip only the final plan confirmation                                  [default = false]
-     [--json]               Emit one stable JSON result and imply non-interactive output           [default = false]
+     [--json]               Emit stable JSON output and disable prompts                            [default = false]
   -h  --help                Print help information and exit
 
 ARGUMENTS
-  [directory]  Policy project directory [default = transcend/policy]
+  [workspace]  Policy workspace directory [default = transcend/policy]
 ```
 
-#### Create the safe default policy project
+#### Create an empty multi-bundle workspace
 
 ```sh
 transcend policy init
 ```
 
-This creates a publishable, fail-closed Rego v1 starter under `transcend/policy`. The example policy is disposable teaching material, not an application contract. Initialization checks local OPA and Regal versions and prints official installation guidance when they are missing or incompatible; it never installs tools or creates runtime-manager configuration.
+This creates a multi-bundle Policy Engine workspace under `transcend/policy` with shared Regal config (`project.roots: []`) and a README. No bundles or Rego are created — add them with `transcend policy new`.
 
-The interactive checklist selects repository-level VS Code setup, the `transcend-policy-engine` Agent Skill, and credential-free validation-only GitHub Actions by default. VS Code setup recommends the official OPA extension, scopes bundle authoring and a default `policy: lint` task to the selected project, and configures strict Rego v1 formatting with Regal.
+The interactive checklist selects repository-level VS Code setup, the `transcend-policy-engine` Agent Skill, and credential-free validation-only GitHub Actions by default. VS Code setup recommends the official OPA extension and configures strict Rego v1 formatting.
 
 To give an agent the same policy guidance before initialization, install the standalone skill directly from this repository:
 
@@ -4346,39 +4389,41 @@ transcend policy init ./policies --dryRun --json
 transcend policy init ./policies --editor --skill --ci --noInteractive --yes
 ```
 
-Non-interactive setup enables only the individual `--editor`, `--skill`, and `--ci` flags passed. There are no setup presets. The complete plan is applied transactionally. Existing or partially initialized policy targets are left unchanged with actionable warnings, including customized Rego, manifests, Regal configuration, README files, workflows, editor values and tasks, and managed skill content.
+Non-interactive setup enables only the individual `--editor`, `--skill`, and `--ci` flags passed. There are no setup presets. The complete plan is applied transactionally. Existing or partially initialized policy targets are left unchanged with actionable warnings.
 
-Generated CI pins OPA 1.13.1, Regal 0.42.0, immutable setup action commits, and the current Transcend CLI release. It runs only `transcend policy lint --noInteractive --json`; it never publishes or adds Transcend API credentials. After successful initialization, copyable one-line next steps and an AI handoff prompt identify the disposable example, repository-specific CI adaptation, and the final lint gate.
+Generated CI pins OPA 1.18.2, Regal 0.42.0, immutable setup action commits, and the current Transcend CLI release. After initialization, the next step is `transcend policy new` to add a bundle from a template.
 
 ### `transcend policy lint`
 
 ```txt
 USAGE
-  transcend policy lint [--dir value] [--fix] [--noInteractive] [--json]
+  transcend policy lint [--fix] [--noInteractive] [--json] [<workspace|bundle>]
   transcend policy lint --help
 
-Validates manifest roots and package coverage, verifies OPA 1.x and Regal, checks or repairs OPA formatting, runs a production-only strict OPA check, treats Regal warnings as failures, and requires non-empty OPA tests. No Transcend API key is needed.
+Defaults to the policy workspace (`transcend/policy`) and verifies every publishable child directory that contains a `.manifest`. Pass one bundle path to verify a single unit. Validates manifest roots and package coverage, verifies OPA 1.x and Regal, checks or repairs OPA formatting, runs a production-only strict OPA check, treats Regal warnings as failures, and requires non-empty OPA tests. No Transcend API key is needed.
 
 FLAGS
-     [--dir]            Directory containing the local policy project                  [default = transcend/policy]
-     [--fix]            Apply OPA formatting without running broad Regal fixes         [default = false]
-     [--noInteractive]  Disable the optional formatting confirmation                   [default = false]
-     [--json]           Emit one stable JSON result and imply non-interactive behavior [default = false]
+     [--fix]            Apply OPA formatting without running broad Regal fixes [default = false]
+     [--noInteractive]  Disable the optional formatting confirmation           [default = false]
+     [--json]           Emit stable JSON output and disable prompts            [default = false]
   -h  --help            Print help information and exit
+
+ARGUMENTS
+  [workspace|bundle]  Policy workspace or bundle directory (workspace runs every .manifest child) [default = transcend/policy]
 ```
 
 #### Examples
 
-**Verify the default local policy project**
+**Verify every bundle under the default workspace**
 
 ```sh
 transcend policy lint
 ```
 
-**Verify and format a custom policy project**
+**Verify and format every bundle under the default workspace**
 
 ```sh
-transcend policy lint --dir=./policies --fix
+transcend policy lint --fix
 ```
 
 **Run the verification gate in CI or an editor**
@@ -4387,6 +4432,73 @@ transcend policy lint --dir=./policies --fix
 transcend policy lint --noInteractive --json
 ```
 
+**Verify a single local publish directory**
+
+```sh
+transcend policy lint transcend/policy/example-bundle --fix
+```
+
+With no directory argument, `policy lint` verifies every immediate child under the default
+workspace (`transcend/policy`) that contains a `.manifest`. Pass one bundle path to verify a
+single unit.
+
+### `transcend policy new`
+
+```txt
+USAGE
+  transcend policy new [--name value] [--bundle-dir value] [--template generic|permissions] [--noInteractive] [--dryRun] [--yes] [--json] [<workspace>]
+  transcend policy new --help
+
+Adds a publishable bundle directory to an initialized policy workspace. `--name` is the Rego package root; `--bundle-dir` is the local folder basename under the workspace (defaults to `{name}-bundle`). This is not the remote Policy Engine `--remote-bundle-name` used at publish time. Requires `.regal/config.yaml` (run `transcend policy init` first). Creates bundle files, merges the root into Regal config, and updates editor setup when present.
+
+FLAGS
+     [--name]           Rego / .manifest package root (not the remote --remote-bundle-name); default folder is {name}-bundle/
+     [--bundle-dir]     Local publish folder basename under the workspace (default: {name}-bundle; not --remote-bundle-name)
+     [--template]       Bundle template                                                                                       [generic|permissions]
+     [--noInteractive]  Disable prompts and require explicit --name and --template                                            [default = false]
+     [--dryRun]         Preview changes without applying them                                                                 [default = false]
+     [--yes]            Skip only the final plan confirmation                                                                 [default = false]
+     [--json]           Emit stable JSON output and disable prompts                                                           [default = false]
+  -h  --help            Print help information and exit
+
+ARGUMENTS
+  [workspace]  Policy workspace directory [default = transcend/policy]
+```
+
+#### Examples
+
+**Add a generic example bundle**
+
+```sh
+transcend policy new --template=generic --name=example --yes
+```
+
+**Add a permissions bundle**
+
+```sh
+transcend policy new --template=permissions --name=permissions --yes
+```
+
+**Custom local folder, same package root**
+
+```sh
+transcend policy new --template=permissions --name=permissions --bundle-dir=my-bundle --yes
+```
+
+**Preview without writing**
+
+```sh
+transcend policy new --template=generic --name=myapp --dryRun --json
+```
+
+Requires an initialized workspace (`transcend policy init` first). Naming triad:
+
+- `--name` — Rego / `.manifest` package root (default local folder: `{name}-bundle/`)
+- `--bundle-dir` — local publish directory basename under the workspace only
+- `--remote-bundle-name` (on `policy publish`) — remote Policy Engine name; unrelated to the local folder
+
+The positional argument is the **workspace** (default `transcend/policy`).
+
 ### `transcend policy bundles`
 
 ```txt
@@ -4398,10 +4510,10 @@ Lists policy bundles registered for the authenticated organization. Requires a T
 
 FLAGS
       --auth              The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
-     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--limit]            Maximum number of bundles to return (1-100)                                                                                                                                                        [default = 50]
-     [--offset]           Number of records to skip before returning results                                                                                                                                                 [default = 0]
-     [--json]             Print the raw JSON API response                                                                                                                                                                    [default = false]
+     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcend-url may be omitted if it is exported. [default = https://api.transcend.io]
+     [--limit]            Maximum number of bundles to return (1-100)                                                                                                                                                         [default = 50]
+     [--offset]           Number of records to skip before returning results                                                                                                                                                  [default = 0]
+     [--json]             Print the raw JSON API response                                                                                                                                                                     [default = false]
      [--debug/--noDebug]  Include technical error details (underlying API message and stack trace) when a command fails
   -h  --help              Print help information and exit
 ```
@@ -4432,38 +4544,39 @@ Requires the **View Policy** scope on your API key.
 
 ```txt
 USAGE
-  transcend policy publish (--dir value) (--bundle-name value) (--auth value) [--transcend-url value] [--version value] [--description value] [--json] [--yes] [--debug]
+  transcend policy publish (--remote-bundle-name value) (--auth value) [--transcend-url value] [--version value] [--description value] [--json] [--yes] [--debug] <bundle>
   transcend policy publish --help
 
-Packages manifest.json and .rego policy files from a local directory into a tarball and uploads it to Transcend. Creates the bundle on first upload, then appends immutable versions. Requires the `opa` CLI on PATH (for `opa check` and `opa build` validation) and a Transcend API key with Manage Policy scope.
+Packages `.manifest` and `.rego` policy files from one local bundle directory into a tarball and uploads it to Transcend. Requires an explicit directory containing a `.manifest`. Creates the bundle on first upload, then appends immutable versions. Requires the `opa` CLI on PATH (for `opa check` and `opa build` validation) and a Transcend API key with Manage Policy scope.
 
 FLAGS
-      --dir               Directory containing manifest.json and Rego policy files
-      --bundle-name       Tenant-unique policy bundle name
-      --auth              The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Manage Policy"
-     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--version]          Version label (defaults to {bundleName}-yyyy-mm-dd-hh-mm-ss)
-     [--description]      Optional description for the uploaded version
-     [--json]             Print the raw JSON API response                                                                                                                                                                    [default = false]
-     [--yes]              Skip the "create new bundle" confirmation (for CI/non-interactive use)                                                                                                                             [default = false]
-     [--debug/--noDebug]  Include technical error details (underlying API message and stack trace) when a command fails
-  -h  --help              Print help information and exit
+      --remote-bundle-name  Remote Policy Engine bundle name (not the local folder or --name root)
+      --auth                The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "Manage Policy"
+     [--transcend-url]      URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcend-url may be omitted if it is exported. [default = https://api.transcend.io]
+     [--version]            Version label (defaults to {bundleName}-yyyy-mm-dd-hh-mm-ss)
+     [--description]        Optional description for the uploaded version
+     [--json]               Print the raw JSON API response                                                                                                                                                                     [default = false]
+     [--yes]                Skip the "create new bundle" confirmation (for CI/non-interactive use)                                                                                                                              [default = false]
+     [--debug/--noDebug]    Include technical error details (underlying API message and stack trace) when a command fails
+  -h  --help                Print help information and exit
+
+ARGUMENTS
+  bundle  Local policy bundle directory containing a .manifest
 ```
 
 #### Examples
 
-**Publish a local policy directory as the main bundle**
+**Publish a local policy bundle as the main bundle**
 
 ```sh
-transcend policy publish --dir=./policies --bundle-name=main --auth="$TRANSCEND_API_KEY"
+transcend policy publish transcend/policy/example-bundle --remote-bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Publish with an explicit version label and description**
 
 ```sh
-transcend policy publish \
-  --dir=./policies \
-  --bundle-name=main \
+transcend policy publish transcend/policy/example-bundle \
+  --remote-bundle-name=main \
   --auth="$TRANSCEND_API_KEY" \
   --version=2026-06-25 \
   --description="Quarterly policy update"
@@ -4472,61 +4585,104 @@ transcend policy publish \
 **Publish to the US-hosted Transcend API**
 
 ```sh
-transcend policy publish \
-  --dir=./policies \
-  --bundle-name=common \
+transcend policy publish transcend/policy/example-bundle \
+  --remote-bundle-name=common \
   --auth="$TRANSCEND_API_KEY" \
   --transcend-url=https://api.us.transcend.io
 ```
 
+**Publish the Permissions API bundle (fixed remote name)**
+
+```sh
+transcend policy publish transcend/policy/permissions-bundle \
+  --remote-bundle-name=permissions \
+  --auth="$TRANSCEND_API_KEY"
+```
+
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy publish --dir=./policies --bundle-name=main
+transcend policy publish transcend/policy/example-bundle --remote-bundle-name=main
 ```
 
+`--remote-bundle-name` is the remote Policy Engine name (not the local folder). The `<bundle>`
+positional is the local publish directory containing a `.manifest`.
+
 Requires the **Manage Policy** scope on your API key.
 
 ### `transcend policy test`
 
 ```txt
 USAGE
-  transcend policy test (--dir value)
+  transcend policy test [--format pretty|json|gobench] [--verbose] [--run value] [--coverage] [--threshold value] [--timeout value] [--var-values] [--explain fails|full|notes|debug] [--schema value] [--exit-zero-on-skipped] [<workspace|bundle>]
   transcend policy test --help
 
-Wraps `opa test` for a local policy directory. Requires the `opa` CLI on PATH. No Transcend API key is needed.
+Defaults to the policy workspace (`transcend/policy`) and runs `opa test -b --fail-on-empty` for every child directory that contains a `.manifest`. Pass one bundle path to test a single unit. Pass-through flags cover format, verbose, run, coverage, threshold, timeout, var-values, explain, schema, and exit-zero-on-skipped; `-b` and `--fail-on-empty` stay owned by the CLI. Requires the `opa` CLI on PATH. No Transcend API key is needed.
 
 FLAGS
-     --dir   Directory containing Rego policy files and tests
-  -h --help  Print help information and exit
+     [--format]                Output format (opa test --format)                                            [pretty|json|gobench, default = pretty]
+     [--verbose]               Show detailed test results (opa test --verbose)                              [default = false]
+     [--run]                   Regex filter for test names (opa test --run)
+     [--coverage]              Report coverage (opa test --coverage)                                        [default = false]
+     [--threshold]             Fail when coverage is below this % (requires --coverage)
+     [--timeout]               Test timeout duration, e.g. 5s (opa test --timeout)
+     [--var-values]            Show variable values in failures (opa test --var-values)                     [default = false]
+     [--explain]               Explanation mode (opa test --explain)                                        [fails|full|notes|debug]
+     [--schema]                JSON Schema file or directory for input type-checking (opa test --schema)
+     [--exit-zero-on-skipped]  Exit 0 when all matching tests are skipped (opa test --exit-zero-on-skipped) [default = false]
+  -h  --help                   Print help information and exit
+
+ARGUMENTS
+  [workspace|bundle]  Policy workspace or bundle directory (workspace runs every .manifest child) [default = transcend/policy]
 ```
 
 #### Examples
 
-**Run tests in a local policy directory**
+**Run tests for every bundle under the default workspace**
+
+```sh
+transcend policy test
+```
+
+**Filter tests and emit JSON**
+
+```sh
+transcend policy test --format=json --run=test_allows --verbose
+```
+
+**Fail CI when coverage is below a threshold**
+
+```sh
+transcend policy test --coverage --threshold=80
+```
+
+**Test a single local publish directory**
 
 ```sh
-transcend policy test --dir=./policies
+transcend policy test transcend/policy/example-bundle
 ```
 
+With no directory argument, `policy test` runs every immediate child under the default workspace
+(`transcend/policy`) that contains a `.manifest`. Pass one bundle path to test a single unit.
+
 ### `transcend policy versions`
 
 ```txt
 USAGE
-  transcend policy versions (--bundle-name value) (--auth value) [--transcend-url value] [--limit value] [--after value] [--json] [--debug]
+  transcend policy versions (--remote-bundle-name value) (--auth value) [--transcend-url value] [--limit value] [--after value] [--json] [--debug]
   transcend policy versions --help
 
 Resolves a bundle name to its UUID and lists uploaded versions. Requires a Transcend API key with View Policy scope.
 
 FLAGS
-      --bundle-name       Tenant-unique policy bundle name
-      --auth              The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
-     [--transcend-url]    URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcendUrl may be omitted if it is exported. [default = https://api.transcend.io]
-     [--limit]            Maximum number of versions to return (1-100)                                                                                                                                                       [default = 50]
-     [--after]            Opaque cursor from a previous response pageInfo.endCursor
-     [--json]             Print the raw JSON API response                                                                                                                                                                    [default = false]
-     [--debug/--noDebug]  Include technical error details (underlying API message and stack trace) when a command fails
-  -h  --help              Print help information and exit
+      --remote-bundle-name  Remote Policy Engine bundle name (not the local folder or --name root)
+      --auth                The Transcend API key. Defaults to the TRANSCEND_API_KEY environment variable when set, so --auth may be omitted if it is exported. Requires scopes: "View Policy"
+     [--transcend-url]      URL of the Transcend backend. Use https://api.us.transcend.io for US hosting. Defaults to the TRANSCEND_API_URL environment variable when set, so --transcend-url may be omitted if it is exported. [default = https://api.transcend.io]
+     [--limit]              Maximum number of versions to return (1-100)                                                                                                                                                        [default = 50]
+     [--after]              Opaque cursor from a previous response pageInfo.endCursor
+     [--json]               Print the raw JSON API response                                                                                                                                                                     [default = false]
+     [--debug/--noDebug]    Include technical error details (underlying API message and stack trace) when a command fails
+  -h  --help                Print help information and exit
 ```
 
 #### Examples
@@ -4534,19 +4690,19 @@ FLAGS
 **List versions for a policy bundle**
 
 ```sh
-transcend policy versions --bundle-name=main --auth="$TRANSCEND_API_KEY"
+transcend policy versions --remote-bundle-name=main --auth="$TRANSCEND_API_KEY"
 ```
 
 **Fetch the next page of versions using an after cursor**
 
 ```sh
-transcend policy versions --bundle-name=main --auth="$TRANSCEND_API_KEY" --after="$POLICY_VERSION_CURSOR"
+transcend policy versions --remote-bundle-name=main --auth="$TRANSCEND_API_KEY" --after="$POLICY_VERSION_CURSOR"
 ```
 
 **Omit --auth by exporting TRANSCEND_API_KEY in the environment**
 
 ```sh
-transcend policy versions --bundle-name=main
+transcend policy versions --remote-bundle-name=main
 ```
 
 Requires the **View Policy** scope on your API key.