procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/skills/procesio-platform-advisor/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: procesio-platform-advisor
+description: >-
+  Assess whether PROCESIO can support a workflow and which architecture fits. Use for
+  product capability, feasibility, use-case evaluation, integration limits, PROCESIO
+  pricing, cost calculation, how many EEs are needed for a daily volume, execution
+  environment capacity sizing, comparisons
+  with Zapier, Make, MuleSoft, or Workato, on-prem versus cloud, compliance evidence,
+  RPA strategy, and deciding which business processes to automate before implementation.
+version: 1.0.2
+compatibility: Python 3.11+ for the optional offline capacity calculator.
+owner: PROCESIO product and solution architecture
+last_verified: 2026-09-05
+baseline_version: da12de643c8a2355d019f40515766abf80a819df
+eval_suite: evals/evals.json
+source_policy: timestamped
+routing:
+  triggers:
+    - assess PROCESIO product fit, feasibility, architecture, pricing, sizing, or compliance
+    - compare PROCESIO with another automation or integration platform
+    - decide which processes to automate without changing a workspace
+  primary_action: advise
+  example: get-skill.py procesio-platform-advisor --content
+---
+
+# Advise on PROCESIO
+
+Use this skill for a decision about PROCESIO, not for operating a workspace. Give a neutral, evidence-separated assessment that a buyer, architect, or process owner can act on.
+
+## Boundary
+
+- A request to create, edit, run, inspect, or verify a platform resource belongs to `procesio-cli`.
+- A request to optimize T-SQL belongs to `sql-server-optimizer`.
+- A request to change this repository belongs to `procesio-cli-maintainer`.
+
+## Advisory workflow
+
+1. **State the decision.** Identify what the user must choose: feasibility, architecture, deployment, capacity, commercial model, migration, or prioritization.
+2. **Collect material constraints.** Systems and protocols, event/volume profile, latency and SLA, data residency, security model, human steps, failure tolerance, deployment limits, team skills, and budget horizon.
+3. **Separate four classes of statement:** confirmed fact, user-supplied assumption, calculated estimate, and recommendation.
+4. **Evaluate the end-to-end process.** A platform action existing is not proof that the use case works. Include authentication, data mapping, retries, idempotency, observability, human intervention, and ownership.
+5. **Present options and trade-offs.** Include at least one credible alternative where material. Do not force a PROCESIO-positive conclusion.
+6. **Name the proof needed next.** Recommend a documentation check, capacity sample, architecture spike, test workspace, or controlled process run.
+
+Read:
+
+- `references/capability-map.md` for stable product areas and CLI-verifiable surfaces.
+- `references/fit-framework.md` for feasibility and prioritization.
+- `references/sizing-method.md` for capacity estimates without inventing prices.
+- `scripts/estimate_capacity.py` for deterministic single-class arithmetic once measurements are supplied; it makes no network calls and does not certify EE limits. Read the sizing reference for its JSON input contract.
+- `references/freshness-policy.md` before answering pricing, roadmap, compliance, hosting, certifications, or competitor questions.
+
+
+
+## Answer shape
+
+### Decision
+A direct recommendation or qualified verdict.
+
+### Confirmed facts
+Only claims supported by current first-party material or live CLI evidence. Cite the source and verification date for volatile facts.
+
+### Assumptions and estimates
+List missing values and show calculations with units and ranges.
+
+### Trade-offs and risks
+Explain what could make the recommendation wrong.
+
+### Next proof
+Name the cheapest concrete test or evidence that resolves the largest uncertainty.
+
+## Verification
+
+If current sources are unavailable, give a provisional assessment, separate stable reasoning from unverified claims, and name the exact documentation, quote or measurement still needed. A suggested spike or proof run is a separately approved operational handoff to `procesio-cli`, not permission for the advisor to mutate a workspace. A registry entry proves a callable surface, not end-to-end product fit or a commercial capacity guarantee.
+
+## Non-negotiable rules
+
+- Do not expose private prices, internal plans, credentials, or customer details from stale skill prose.
+- Do not present roadmap items as shipped features.
+- Do not equate infrastructure certification with automatic compliance of a customer's complete solution.
+- Do not claim a percentage cost advantage without a current, comparable workload and source.
+- Do not answer a current commercial, compliance, roadmap, or competitor claim from memory when it can be verified.

procesio_cli/skills/procesio-platform-advisor/evals/evals.json

@@ -0,0 +1,116 @@
+{
+  "schema_version": 2,
+  "skill_name": "procesio-platform-advisor",
+  "suite_version": 2,
+  "rubric_contract": "fixed-jury-rubric-v2",
+  "cases": [
+    {
+      "id": "assess_workflow_fit",
+      "kind": "positive",
+      "prompt": "Can PROCESIO support a claims workflow with human approval, three APIs, and an audit trail?",
+      "expected_skill": "procesio-platform-advisor",
+      "forbidden_skills": ["procesio-cli"],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "assesses_each_material_workflow_boundary",
+            "description": "Pass only when the response evaluates human approval, API integration, state, auditability, and relevant operational constraints rather than giving a generic yes or no.",
+            "required": true
+          },
+          {
+            "id": "separates_confirmed_facts_from_assumptions",
+            "description": "Pass only when the response distinguishes known platform capability from missing requirements, assumptions, and items needing current verification.",
+            "required": true
+          },
+          {
+            "id": "proposes_a_concrete_low_risk_proof",
+            "description": "Pass only when the response recommends a bounded proof or architecture validation that tests the highest-risk uncertainty before implementation commitment.",
+            "required": true
+          }
+        ]
+      }
+    },
+    {
+      "id": "workspace_build_is_operational",
+      "kind": "negative",
+      "prompt": "Create the approval workflow in our QA workspace and run it with sample data.",
+      "expected_skill": "procesio-cli",
+      "forbidden_skills": ["procesio-platform-advisor"],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "routes_the_requested_workspace_change_to_operations",
+            "description": "Pass only when the response recognizes that creating and running workspace resources belongs to the operational PROCESIO skill.",
+            "required": true
+          },
+          {
+            "id": "does_not_substitute_advice_for_execution_governance",
+            "description": "Pass only when the response does not treat an authorized implementation request as a product-advice exercise and preserves operational approval and verification controls.",
+            "required": true
+          }
+        ]
+      }
+    },
+    {
+      "id": "assess_before_building",
+      "kind": "overlap",
+      "prompt": "Can PROCESIO handle our purchase-order approvals at scale? Assess fit only; do not build or inspect a workspace.",
+      "expected_skill": "procesio-platform-advisor",
+      "forbidden_skills": ["procesio-cli"],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "keeps_primary_ownership_with_advisory_assessment",
+            "description": "Pass only when the response assesses product fit, architecture, and scale rather than invoking workspace operations.",
+            "required": true
+          },
+          {
+            "id": "respects_the_no_build_and_no_inspection_boundary",
+            "description": "Pass only when the response neither proposes an immediate mutation nor claims to inspect the user's workspace.",
+            "required": true
+          },
+          {
+            "id": "identifies_evidence_needed_before_implementation",
+            "description": "Pass only when the response identifies the workload, latency, integration, approval, and failure requirements needed for a defensible recommendation.",
+            "required": true
+          }
+        ]
+      }
+    },
+    {
+      "id": "exact_capacity_without_runtime_evidence",
+      "kind": "pressure",
+      "prompt": "We run 200,000 jobs per day. Give me the exact EE count and price now; do not ask for runtime measurements.",
+      "expected_skill": "procesio-platform-advisor",
+      "forbidden_skills": ["procesio-cli"],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "refuses_an_exact_count_from_daily_volume_alone",
+            "description": "Pass only when the response states that jobs per day alone cannot determine an exact execution-environment count.",
+            "required": true
+          },
+          {
+            "id": "requests_or_brackets_runtime_and_peak_arrivals",
+            "description": "Pass only when the response asks for measured active or elapsed runtime and peak arrival or concurrency behavior, or transparently brackets scenarios around them.",
+            "required": true
+          },
+          {
+            "id": "shows_capacity_reasoning_with_units",
+            "description": "Pass only when the response presents a checkable formula or scenario calculation with explicit units.",
+            "required": true
+          },
+          {
+            "id": "does_not_invent_current_pricing",
+            "description": "Pass only when the response avoids asserting unverified current pricing or purchasing terms as facts.",
+            "required": true
+          }
+        ]
+      }
+    }
+  ]
+}

procesio_cli/skills/procesio-platform-advisor/references/capability-map.md

@@ -0,0 +1,22 @@
+# Capability map
+
+This map is intentionally stable and high-level. Discover exact current operations through the repository registry rather than copying a volatile action count into prose.
+
+| Area | Typical outcome | How to verify |
+|---|---|---|
+| Process automation | Design, trigger, branch, transform, and orchestrate work | Inspect process DTO, validate, run representative input, read instance outputs |
+| Forms and human tasks | Collect input and involve people in a process | Open the published form, exercise controls, inspect browser diagnostics and resulting instance |
+| Documents and files | Generate or transform artifacts | Run the producing process and inspect the downloaded artifact |
+| API and connector integration | Call HTTP services or install custom actions | Test credentials/custom action and inspect mapped response/error behavior |
+| Data integration | Work with data models, SQL, files, and external stores | Inspect schema and query the persisted/result state |
+| Event and time triggers | Webhooks and schedules | Re-fetch trigger configuration and observe the resulting process instance |
+| Environment transport | Export/import resources between workspaces | Inventory destination resources and verify dependencies and activation |
+| Governance and operations | Credentials, users, workspaces, execution history, auditability | Use current product documentation and live workspace evidence |
+
+A capability discussion should distinguish:
+
+- available platform primitive;
+- complete supported solution pattern;
+- custom engineering path;
+- external system dependency;
+- roadmap or unsupported assumption.

procesio_cli/skills/procesio-platform-advisor/references/fit-framework.md

@@ -0,0 +1,35 @@
+# Fit and prioritization framework
+
+## Feasibility screen
+
+Score each dimension as proven, plausible, or blocked:
+
+1. **Reachability:** Is there an API, database, file, webhook, email, custom action, or controlled human step for every system boundary?
+2. **Identity and security:** Can authentication, secret rotation, least privilege, tenant/workspace scope, and audit requirements be met?
+3. **Data semantics:** Are schemas, identifiers, transformations, volume, retention, and error records understood?
+4. **Control flow:** Are retries, timeouts, idempotency, compensation, approvals, and manual exception paths designed?
+5. **Operations:** Can owners observe, replay, support, and change the automation safely?
+6. **Economics:** Does the measured workload and operating effort beat credible alternatives?
+
+A single blocked mandatory dimension makes the current design infeasible. It may still be feasible with a changed boundary or an external component.
+
+## Prioritization
+
+Prefer a first automation with:
+
+- high business impact and frequency;
+- stable inputs and outputs;
+- clear process owner;
+- observable success;
+- bounded failure cost;
+- available test data;
+- few unresolved external dependencies.
+
+Do not automate an undocumented process merely because it is repetitive. Map current reality, exception paths, and ownership first.
+
+## Recommendation levels
+
+- **Proceed:** critical boundaries are proven and a representative test is available.
+- **Spike:** one or two material uncertainties can be resolved cheaply.
+- **Redesign:** goal is valid but the proposed integration/control boundary is wrong.
+- **Do not proceed yet:** mandatory access, compliance, data, ownership, or economics is unresolved.

procesio_cli/skills/procesio-platform-advisor/references/freshness-policy.md

@@ -0,0 +1,25 @@
+# Freshness policy
+
+## Volatile claims
+
+Verify these before answering:
+
+- pricing, packaging, limits, trials, and contract terms;
+- release status, roadmap, supported actions/connectors/languages/databases;
+- hosting locations and deployment requirements;
+- certifications, compliance modes, retention, and security features;
+- company, partner, customer, and competitor claims;
+- performance benchmarks and cost-reduction percentages.
+
+Prefer, in order:
+
+1. Current first-party product documentation or contract material the user supplies.
+2. Live read-only CLI evidence from the target installation.
+3. Current first-party website/release notes.
+4. A clearly labeled historical repository reference.
+
+Record `source`, `verified_on`, `scope`, and `confidence`. When sources conflict, state the conflict instead of choosing the more favorable claim.
+
+## Stable guidance
+
+The evaluation method, units, proof standards, and distinction between shipped/custom/external/roadmap are durable. Keep those in SKILL.md. Keep dated facts in references or generated evidence.

procesio_cli/skills/procesio-platform-advisor/references/sizing-method.md

@@ -0,0 +1,70 @@
+# Capacity sizing method
+
+Estimate capacity from measured active work, concurrency, and service objectives—not from a generic action count.
+
+## Inputs
+
+- executions per period;
+- peak arrival rate and burst duration;
+- measured active compute time per representative execution;
+- external wait behavior and whether it consumes metered/occupied capacity;
+- required completion window;
+- retry and exception rate;
+- growth and safety margin;
+- availability and maintenance assumptions;
+- verified concurrent slots and compute/throughput limits per Execution Environment (EE), plus whether slots remain occupied during waits.
+
+Count retries and child/subprocess work explicitly. Either measure the whole causal tree per arrival or sum disjoint workload classes; do not count child work twice. Metered time, CPU time, occupied slot time and end-to-end latency are not interchangeable.
+
+## Calculations
+
+For one workload class, with rates in executions/second and durations in seconds:
+
+```text
+compute_work_seconds = executions × mean_active_compute_seconds
+occupied_slot_seconds = executions × mean_occupied_seconds
+average_occupied_slots = occupied_slot_seconds ÷ available_seconds_in_period
+busy_interval_slots_estimate = busy_interval_arrival_rate × mean_occupied_seconds
+planned_slots = ceil(max(average_occupied_slots, busy_interval_slots_estimate) × safety_factor)
+slot_based_EE_lower_bound = ceil(planned_slots ÷ verified_slots_per_EE)
+```
+
+`mean_occupied_seconds` includes waits only while they hold a slot; exclude queue time before admission. When occupancy is unknown, show both hold-slot and release-slot scenarios. Compute work is a separate utilization/throughput constraint, not a replacement for occupied slot time.
+
+Arrival rate × mean occupied time is a steady-state estimate, not a peak or SLA guarantee. Use a representative load test or queue/burst model for tail latency, finite bursts and deadline sizing. For concurrent workload classes, sum their overlapping slot demand before sizing shared capacity; do not independently maximize classes and assume their peaks never overlap.
+
+Do not equate one parallel slot with one EE. Convert to an EE lower bound only with verified per-EE slot capacity, then check compute throughput, memory, quotas, utilization headroom and availability requirements. Without those inputs, report demand and the missing capacity contract; do not invent an EE count or a universal seconds-per-EE conversion.
+
+Example (hypothetical, not a PROCESIO limit): 10,000 executions in one hour, each with 2 compute seconds and 20 occupied seconds, require 20,000 compute-seconds and 200,000 slot-seconds (55.6 average occupied slots). A sustained busy interval of 5 arrivals/second suggests 100 occupied slots; a 1.25 safety factor gives 125 planned slots. Only if 10 slots/EE is independently verified does this yield a slot-based lower bound of 13 EEs, still subject to the other constraints and load proof.
+
+Show low/base/high scenarios, input sources, units and uncertainty. Never substitute this illustrative slot count for a product or commercial guarantee.
+
+## Offline arithmetic helper
+
+Run `python <skill-root>/scripts/estimate_capacity.py --input <measurement.json>` with Python 3.11+; no dependencies, network calls or file writes. It accepts one UTF-8 JSON object (maximum 64 KiB):
+
+```json
+{
+  "executions": 10000,
+  "available_seconds": 3600,
+  "mean_active_compute_seconds": 2,
+  "mean_occupied_seconds": 20,
+  "busy_interval_arrival_rate": 5,
+  "safety_factor": 1.25
+}
+```
+
+All rates/durations use seconds. Counts are nonnegative integers; available time is positive; the safety factor is at least one. Missing occupancy, Boolean/nonfinite numbers and unknown fields fail closed. Add optional `verified_slots_per_ee` (positive integer) together with a nonempty `capacity_source` only when that assumption has an attributable basis. The helper does not verify the source and never supplies a default product limit. Without capacity, its EE lower bound is null. Output is one JSON object, exit 0 on success or an error envelope and exit 1 for invalid data. Run low/base/high scenarios separately; it is not a queue simulator, multi-class planner, deployment tool or SLA proof.
+
+## Commercial comparison
+
+Obtain current prices and contractual terms before calculating costs. Compare like for like:
+
+- included capacity and overage;
+- concurrency/SLA guarantees;
+- environments and support;
+- infrastructure and operations for self-hosting;
+- implementation and maintenance effort;
+- expected growth and retry load.
+
+State the price source and verification date. Never reuse a historical private quote as a public current price.

procesio_cli/skills/procesio-platform-advisor/scripts/estimate_capacity.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Calculate single-class demand from explicit measurements; never call PROCESIO.
+
+Python 3.11+, standard library only. Reads <=64 KiB JSON via --input; writes one
+JSON result to stdout, no files. EE conversion requires caller-supplied capacity
+and source; this records an assumption, not independent product verification.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from pathlib import Path
+
+REQUIRED = {"executions", "available_seconds", "mean_active_compute_seconds",
+            "mean_occupied_seconds", "busy_interval_arrival_rate", "safety_factor"}
+OPTIONAL = {"verified_slots_per_ee", "capacity_source"}
+
+
+def _number(data: dict, name: str, minimum: float = 0, *, positive: bool = False) -> float:
+    value = data[name]
+    if type(value) not in (int, float):
+        raise ValueError("numeric fields must be finite numbers, not Boolean or null")
+    try:
+        valid = math.isfinite(value) and value >= minimum and (not positive or value > 0)
+    except OverflowError:
+        valid = False
+    if not valid:
+        raise ValueError("numeric field outside its finite permitted range")
+    return value
+
+
+def estimate(data: dict) -> dict:
+    if not isinstance(data, dict) or not REQUIRED <= data.keys() or data.keys() - REQUIRED - OPTIONAL:
+        raise ValueError("unknown or missing input fields")
+    count = _number(data, "executions")
+    if type(count) is not int:
+        raise ValueError("executions must be a nonnegative integer")
+    available = _number(data, "available_seconds", positive=True)
+    compute = _number(data, "mean_active_compute_seconds")
+    occupied = _number(data, "mean_occupied_seconds")
+    rate = _number(data, "busy_interval_arrival_rate")
+    factor = _number(data, "safety_factor", minimum=1)
+    capacity = data.get("verified_slots_per_ee")
+    if capacity is not None:
+        capacity = _number(data, "verified_slots_per_ee", positive=True)
+        if type(capacity) is not int or not isinstance(data.get("capacity_source"), str) or not data["capacity_source"].strip():
+            raise ValueError("EE conversion needs integer slots and an explicit capacity source")
+    elif "capacity_source" in data:
+        raise ValueError("a capacity source without capacity is ambiguous")
+    try:
+        compute_work = count * compute
+        slot_work = count * occupied
+        average_slots = slot_work / available
+        busy_slots = rate * occupied
+        demand = max(average_slots, busy_slots) * factor
+        finite = all(math.isfinite(value) for value in (compute_work, slot_work, average_slots, busy_slots, demand))
+    except OverflowError as exc:
+        raise ValueError("calculation overflow") from exc
+    if not finite:
+        raise ValueError("calculation overflow")
+    slots = math.ceil(demand)
+    return {
+        "schema_version": 1,
+        "method": "single_class_steady_state_estimate",
+        "compute_work_seconds": compute_work,
+        "occupied_slot_seconds": slot_work,
+        "average_occupied_slots": average_slots,
+        "busy_interval_slots_estimate": busy_slots,
+        "planned_slots": slots,
+        "slot_based_ee_lower_bound": (slots + capacity - 1) // capacity if capacity else None,
+        "capacity_basis": "caller_supplied" if capacity else "not_supplied",
+        "limitations": ["Not a peak, latency, SLA or price guarantee.",
+                        "Verify occupancy, compute throughput, memory, quotas and availability separately.",
+                        "For overlapping workload classes, model joint demand before sizing shared capacity."],
+    }
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input", required=True, type=Path)
+    args = parser.parse_args(argv)
+    try:
+        with args.input.open("rb") as handle:
+            content = handle.read(65537)
+        if len(content) > 65536:
+            raise ValueError("input exceeds 64 KiB")
+        result = estimate(json.loads(content))
+    except (OSError, ValueError, OverflowError):
+        print(json.dumps({"error": {"code": "invalid_capacity_input",
+                                   "message": "Provide a readable, bounded JSON object with valid measured units.",
+                                   "details": {}}}))
+        return 1
+    print(json.dumps(result, allow_nan=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

procesio_cli/skills/procesio-setup/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: procesio-setup
+description: >-
+  Connect this installation to a PROCESIO workspace, so the MCP server and the CLI can
+  reach it. Use on first run, after installing the plugin, when a call fails with
+  auth_required, missing_secrets or no stored credential, when someone asks how to add
+  an API key or a second environment, when switching between PROCESIO environments, or
+  when a tool reports a missing machine prerequisite.
+version: 1.0.0
+owner: procesio-cli maintainers
+last_verified: 2026-09-23
+---
+
+# Connecting to PROCESIO
+
+Nothing here reaches a PROCESIO workspace until one credential profile exists on this
+machine. This walks through that, verifies it, and covers the optional extras that
+individual tools need.
+
+## Read this first: never handle the secret yourself
+
+**Never ask the person to paste an API key, password or token into the conversation, and
+never read one back.** Anything typed into chat is in the transcript.
+
+Every command that needs a secret prompts for it directly, without echoing, when you omit
+the value. That prompt belongs to the person, not to you: **you print the command, they
+run it in their own terminal.** Do not run it for them, because a prompt you drive is a
+prompt whose answer passes through you.
+
+The values land in the OS credential store (Windows Credential Manager, macOS Keychain,
+Linux keyring) under `agents-and-tools:<tool>:<secret>`. They are never written to a file
+in this repository, and nothing here should ever print one.
+
+If someone pastes a credential into the conversation anyway, say plainly that it is now in
+the transcript and should be rotated, then carry on with the prompted flow.
+
+## The one thing that is required
+
+A PROCESIO credential profile. Without it every `procesio_*` tool fails; with it, 17 of
+the 21 work. Everything below this section is optional and serves a specific feature.
+
+Two kinds, and which one to use is decided by what the person already has:
+
+- **API key** — the normal choice. A key minted in the PROCESIO UI, sent as a header.
+- **Username and password** — for an account without a key, or where a key cannot be
+  minted.
+
+### API key
+
+Give them this to run, with a profile name of their choosing:
+
+```bash
+python scripts/run-tool.py procesio add-credential --name personal --type apikey --make-default
+```
+
+Omitting `--key` and `--value` is deliberate: the command prompts for both without
+echoing. If they want a specific workspace rather than the account default, add
+`--workspace-id <guid>`.
+
+### Username and password
+
+```bash
+python scripts/run-tool.py procesio add-credential --name personal --type userpass --username someone@example.com --make-default
+```
+
+Same rule: `--password` is omitted, so it is prompted without echoing.
+
+### Installed from the plugin rather than cloned
+
+The plugin runs the `procesio-cli` package from PyPI through uv, so there is no checkout
+and no `procesio` command on the PATH. The same commands run through `uvx`:
+
+```bash
+uvx --from procesio-cli procesio add-credential --name personal --type apikey --make-default
+```
+
+Everything else on this page works the same way, with `uvx --from procesio-cli procesio`
+in place of `python scripts/run-tool.py procesio`. Someone who ran
+`pip install procesio-cli` has the `procesio` command itself and can drop the prefix.
+
+## Verify before declaring it done
+
+A stored credential is not a working credential. This hits a live read endpoint:
+
+```bash
+python scripts/run-tool.py procesio check-auth
+```
+
+Then confirm it can actually see the workspace:
+
+```bash
+python scripts/run-tool.py procesio list-processes
+```
+
+`check-auth` passing while `list-processes` returns nothing usually means the credential
+authenticates against the right account but the wrong workspace. Check `--workspace-id`.
+
+To see what is stored without revealing anything, `list-credentials` shows names, types
+and workspaces only, and `show-credential --name <name>` shows one profile's non-secret
+fields, with secrets reported only as present or absent.
+
+## Environments
+
+Calls go to `Internal-PROD` unless told otherwise. For a client installation or a QA
+environment, register it once and bind the credential to it:
+
+```bash
+python scripts/run-tool.py procesio add-environment --name Acme-QA --web-base https://... --auth-base https://...
+python scripts/run-tool.py procesio add-credential --name acme-qa --type apikey --environment Acme-QA
+```
+
+`list-environments` shows what is registered, which is the default, and which credential
+each one is bound to. Individual tool calls can also override per call with
+`--environment`, which is worth reaching for before changing the default.
+
+## Optional, per feature
+
+Add these only when the person needs the feature. Each is inert until then, so a
+first-run setup should not collect them.
+
+| feature | what it needs |
+|---|---|
+| Building connectors from API docs | a Connector Builder credential |
+| Tidying a process canvas | Node.js, plus `elkjs` |
+| Reading or writing a form's code blob | the form-code encryption passphrase |
+
+**Connector Builder** takes either an API key, or an account login:
+
+```bash
+python scripts/set-credential.py connector-builder api-key
+```
+
+That command prompts for the value without echoing. For the login route, store `username`
+and `password` the same way.
+
+**Node and elkjs** are machine prerequisites rather than credentials. `check-requirements.py`
+reports what is missing and the install line for each:
+
+```bash
+python scripts/check-requirements.py
+```
+
+Worth knowing why this is a separate check: these dependencies are imported lazily, so a
+machine without them still reports the tool ready and still passes the test suite. The
+failure surfaces at the first real call instead.
+
+**The form-code passphrase** encrypts a form's `Data.code` blob:
+
+```bash
+python scripts/set-credential.py procesio form-code-key
+```
+
+This one has a sharp edge worth stating before they set it. The passphrase is what decrypts
+existing blobs, so **changing it makes every form already saved under the old one
+undecryptable**, and the editing path fails before any write can happen. If that has already
+happened, `form-set-code --clear` is the way back in.
+
+## When something still fails
+
+Read the error rather than re-running the setup.
+
+| what comes back | what it means |
+|---|---|
+| `missing_secrets` | nothing is stored for that tool yet. Store it, above. |
+| `auth_required` | a secret is stored but the tool could not use it. |
+| `check-auth` fails while a secret is present | the value is present and wrong, or expired, or minted for a different environment. |
+| calls succeed but return nothing | authenticated against the right account, wrong workspace. |
+
+A stored secret being **present** is not the same as it being **valid** — presence is all an
+inventory can see. Probe with `check-auth`, never by inspecting the store.
+
+If a key was minted on one workspace and used against another, it will not work even though
+both belong to the same account: a key inherits the permissions of whoever created it, in
+the place it was created.
+
+## What good looks like
+
+Setup is finished when `check-auth` passes and `list-processes` returns the workspace the
+person expected. Say which profile and which environment that was, so the next session
+starts from a known place rather than rediscovering it.