procesio-cli 0.1.1__tar.gz

procesio_cli-0.1.1/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "procesio-cli",
+  "description": "Source for the official PROCESIO plugin: the CLI, its MCP server and the Agent Skills that carry the build, verify and audit method.",
+  "owner": {
+    "name": "Ringhel TEAM SRL (PROCESIO)",
+    "url": "https://procesio.com"
+  },
+  "plugins": [
+    {
+      "name": "procesio",
+      "source": "./plugin",
+      "description": "Lets your own AI assistant build, run, validate and audit PROCESIO processes, forms and documents."
+    }
+  ]
+}

procesio_cli-0.1.1/.gitattributes

@@ -0,0 +1,11 @@
+# Preserve bytes exactly as published.
+#
+# This tree is a byte-identical copy of files maintained in an internal monorepo,
+# and a patch sent here is ported back to the same path there. End-of-line
+# rewriting on checkout or commit would break that equivalence and would make the
+# publication tool's `diff` report every rewritten file as changed forever, which
+# is how real drift stops being visible.
+#
+# `-text` disables eol conversion without marking anything binary, so GitHub and
+# `git diff` still render normal text diffs.
+* -text

procesio_cli-0.1.1/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Every pull request gets a review from the maintainers.
+*       @Procesio-Externals/maintainers
+
+# Narrower ownership, if you want it:
+# /tools/procesio/          @Procesio-Externals/devs
+# /tools/connector-builder/ @Procesio-Externals/devs
+# /.github/                 @Procesio-Externals/maintainers

procesio_cli-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Something in the toolkit doesn't work.
+labels: ["bug", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before you fill this in: don't paste credentials, `.procesio` export
+        files, real workspace GUIDs, or customer data. Redact them.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: The command you ran, and the steps that lead to it.
+      placeholder: |
+        1. python scripts/run-tool.py procesio ...
+        2. ...
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Output or traceback
+      render: shell
+
+  - type: dropdown
+    id: tool
+    attributes:
+      label: Which tool
+      options:
+        - procesio
+        - connector-builder
+        - web
+        - xlsx
+        - sqlserver
+        - mysql
+        - dashboard
+        - framework-map
+        - An agent or a skill
+        - The framework itself
+        - I don't know
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Windows
+        - macOS
+        - Linux desktop
+        - Linux headless
+    validations:
+      required: true
+
+  - type: input
+    id: versions
+    attributes:
+      label: Python version and commit
+      placeholder: "Python 3.12.4, commit a1b2c3d"
+    validations:
+      required: true

procesio_cli-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or idea
+    url: https://github.com/Procesio-Externals/procesio-cli/discussions
+    about: Ask how something works, or float an idea that isn't a request yet.
+  - name: Security vulnerability
+    url: https://github.com/Procesio-Externals/procesio-cli/security/advisories/new
+    about: Report privately. Don't open a public issue.
+  - name: PROCESIO platform support
+    url: https://procesio.com
+    about: For the platform itself rather than this toolkit. Sign in at https://procesio.app.

procesio_cli-0.1.1/.github/ISSUE_TEMPLATE/docs.yml

@@ -0,0 +1,24 @@
+name: Documentation problem
+description: Something in the docs is wrong, missing, or hard to follow.
+labels: ["documentation", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For a typo, you don't need an issue. Open the file, click the pencil
+        icon, and GitHub opens a pull request for you.
+
+  - type: input
+    id: where
+    attributes:
+      label: Which file or page
+      placeholder: "README.md, the credentials section"
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong
+    validations:
+      required: true

procesio_cli-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature request
+description: Suggest a tool, an action, or a change in behavior.
+labels: ["enhancement", "needs triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What you're trying to do
+      description: Describe the task, not the solution. What can't you do today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you'd like
+      description: If you have a shape in mind, sketch the command or the API.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you do instead today
+      description: The workaround, if you have one.
+
+  - type: dropdown
+    id: contribute
+    attributes:
+      label: Would you like to build it?
+      options:
+        - "Yes, if a maintainer agrees on the approach"
+        - "No, I'm suggesting it"
+    validations:
+      required: true

procesio_cli-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## What this changes
+
+<!-- One or two sentences. Link the issue if there is one: Fixes #123 -->
+
+## Why
+
+<!-- What breaks, or what you can't do, without this change. -->
+
+## How you tested it
+
+<!-- Commands you ran, and the platform version or environment if it matters. -->
+
+## Checklist
+
+- [ ] `uv run pytest` passes.
+- [ ] I added a test, or this change can't be tested.
+- [ ] I didn't move or rename any file.
+- [ ] There are no credentials, `.procesio` export files, real workspace GUIDs,
+      customer data, or personal names in the diff.
+- [ ] **Allow edits by maintainers** is checked.

procesio_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    # The credential store is per-OS, so it is tested per-OS. A change that only
+    # works on the maintainer's machine is exactly what this matrix is for.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          # Without this the matrix is decoration: uv picks its own interpreter,
+          # every job runs the same one, and the job names claim a coverage the
+          # run does not have.
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras --python ${{ matrix.python-version }}
+      - name: tests
+        # Every suite the repo ships, not just the two obvious ones: the
+        # dashboard and the MCP bridge carry tests too, and leaving them out
+        # meant a green CI that had never exercised either.
+        run: uv run pytest tools agents dashboard webplatform -q
+      - name: no secrets in tracked files
+        run: uv run python scripts/secret_scan.py
+      - name: generated files are current
+        run: |
+          uv run python scripts/build-router.py --check
+      - name: skills are valid
+        # The manuals are generated, and a generated file nothing parses is how
+        # 35 of them shipped with invalid YAML frontmatter. The validator is the
+        # thing that would have caught it.
+        run: uv run python scripts/validate-skills.py
+      - name: both MCP surfaces start, and the plugin launches the one plugin/.mcp.json names
+        # The launch command is read OUT of .mcp.json rather than repeated here. A gate
+        # that names its own command stops testing the plugin the moment the config
+        # points somewhere else, and stays green the whole time it is not testing it.
+        #
+        # Proving this here is the only place it gets proven: a plugin that installs and
+        # then fails to start is indistinguishable from a broken product. Both surfaces
+        # are checked because both ship - the curated one the plugin uses, and the full
+        # registry one anybody can still configure by hand.
+        if: runner.os == 'Linux'
+        run: |
+          python - <<'PY'
+          import json, pathlib, subprocess
+
+          # The plugin pins the PyPI release ("procesio-cli==<version>"), which does not
+          # exist yet while its pull request is open, so the checkout stands in for it.
+          # Everything else in the command (pins, interpreter choice) runs as shipped.
+          cfg = json.loads(pathlib.Path("plugin/.mcp.json").read_text())["mcpServers"]["procesio"]
+          args = [a.replace("${CLAUDE_PLUGIN_ROOT}", "plugin") for a in cfg["args"]]
+          release = args[args.index("--from") + 1]
+          if not release.startswith("procesio-cli=="):
+              raise SystemExit(f"plugin/.mcp.json must pin an exact release, got {release!r}")
+          args[args.index("--from") + 1] = "."
+          plugin_argv = [cfg["command"]] + args
+          request = '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n'
+
+          for label, argv in (
+              ("plugin, per plugin/.mcp.json", plugin_argv),
+              ("full registry surface", ["uvx", "--python-preference", "system",
+                                         "--python", ">=3.11",
+                                         "--from", ".", "--constraints", "constraints.txt",
+                                         "--build-constraints", "build-constraints.txt",
+                                         "procesio-mcp"]),
+          ):
+              proc = subprocess.run(argv, input=request, capture_output=True,
+                                    text=True, timeout=600)
+              if proc.returncode != 0:
+                  raise SystemExit(f"{label}: exited {proc.returncode}\n{proc.stderr[-2000:]}")
+              tools = json.loads(proc.stdout.splitlines()[0])["result"]["tools"]
+              if not tools:
+                  raise SystemExit(f"{label}: started but listed no tools")
+              print(f"{label}: {len(tools)} tools via {' '.join(argv)}")
+          PY

procesio_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,164 @@
+name: release
+
+# Publishing is driven by a tag, so the thing released is always a commit someone
+# deliberately marked. One tag produces three things:
+#   1. a GitHub release carrying procesio-mcp-<version>.mcpb, the one-click MCP bundle;
+#   2. the PyPI package, only once the repository variable PYPI_PUBLISH is "true";
+#   3. the entry in the official MCP Registry, io.github.Procesio-Externals/procesio-cli.
+# Nothing here holds a token. PyPI and the MCP Registry both take the job's identity over
+# OIDC: PyPI once trusted publishing is configured on pypi.org against this repository,
+# this workflow file and the `pypi` environment; the registry needs nothing configured,
+# because a GitHub OIDC token from this repository is what owns the io.github namespace.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      # Third-party actions are pinned to a commit SHA, not a moving tag: a tag can be
+      # repointed at new code, and this workflow holds id-token: write. The trailing
+      # comment records which release the SHA was, so a bump stays a reviewable change.
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+      - name: build wheel and sdist
+        run: uv build
+      - name: the tag and the package version must agree
+        # A tag that says one thing while the metadata says another is how a release
+        # ends up unreproducible. Cheaper to fail here than to yank from PyPI.
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(ls dist/*.tar.gz | sed -E 's/.*-([0-9][^-]*)\.tar\.gz/\1/')
+          echo "tag=$tag package=$pkg"
+          test "$tag" = "$pkg"
+        if: startsWith(github.ref, 'refs/tags/v')
+      - name: the built package installs and runs
+        # Installed into a clean environment, not the checkout: this is what catches a
+        # wheel that builds but ships an incomplete tree.
+        run: |
+          uv venv /tmp/verify
+          VIRTUAL_ENV=/tmp/verify uv pip install dist/*.whl
+          cd /tmp && /tmp/verify/bin/procesio-tools > /dev/null
+          echo "entry points run from an installed package"
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    # Off until trusted publishing exists on pypi.org: without it this job can only fail,
+    # and the registry entry below must not list a package PyPI does not have.
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    # The environment is the approval gate: require a reviewer on it in the repository
+    # settings and a release cannot go out on a tag push alone.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/procesio-cli
+    permissions:
+      id-token: write      # OIDC, so no API token is stored anywhere
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  mcpb:
+    name: build the MCP bundle and attach it to the release
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write      # creates the GitHub release that hosts the bundle
+    outputs:
+      sha256: ${{ steps.pack.outputs.sha256 }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "lts/*"
+      - name: pack
+        id: pack
+        # The bundle is the tracked tree plus mcpb/manifest.json at its root. It is a
+        # "uv" bundle: the host installs the dependencies from pyproject.toml, so the
+        # file stays small and carries no compiled code.
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          mkdir -p build/bundle dist
+          git archive HEAD | tar -x -C build/bundle
+          cp mcpb/manifest.json build/bundle/manifest.json
+          test "$(jq -r .version build/bundle/manifest.json)" = "$version"
+          npx -y @anthropic-ai/mcpb@2.1.2 validate build/bundle/manifest.json
+          npx -y @anthropic-ai/mcpb@2.1.2 pack build/bundle "dist/procesio-mcp-$version.mcpb"
+          sha=$(sha256sum "dist/procesio-mcp-$version.mcpb" | cut -d' ' -f1)
+          echo "sha256=$sha" >> "$GITHUB_OUTPUT"
+          echo "procesio-mcp-$version.mcpb sha256 $sha"
+      - name: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/*.mcpb --verify-tag --title "$GITHUB_REF_NAME" --notes-file CHANGELOG.md
+
+  mcp-registry:
+    name: publish to the MCP Registry
+    needs: [mcpb, publish]
+    # Runs whether or not the PyPI job ran; it only refuses when something it needs failed.
+    if: >-
+      always() && needs.mcpb.result == 'success' &&
+      (needs.publish.result == 'success' || needs.publish.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write      # the GitHub OIDC token is the registry login
+      contents: read
+    env:
+      # Pinned and checksummed rather than releases/latest: this binary runs with an
+      # OIDC token in reach. Bump both values together, from the release's checksums file.
+      MCP_PUBLISHER_VERSION: v1.8.1
+      MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - name: fill in server.json for this release
+        # server.json is immutable once a version is in the registry, so everything in it
+        # is checked here: the version must be the tag, the bundle hash is the one just
+        # built, and the PyPI package is listed only when PyPI really has it.
+        env:
+          MCPB_SHA256: ${{ needs.mcpb.outputs.sha256 }}
+          PYPI_PUBLISH: ${{ vars.PYPI_PUBLISH }}
+        run: |
+          python3 - <<'PY'
+          import json, os
+          version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          doc = json.load(open("server.json", encoding="utf-8"))
+          assert doc["version"] == version, (doc["version"], version)
+          packages = []
+          for pkg in doc["packages"]:
+              if pkg["registryType"] == "mcpb":
+                  assert version in pkg["identifier"], pkg["identifier"]
+                  pkg["fileSha256"] = os.environ["MCPB_SHA256"]
+              elif pkg["registryType"] == "pypi" and os.environ.get("PYPI_PUBLISH") != "true":
+                  continue
+              packages.append(pkg)
+          doc["packages"] = packages
+          json.dump(doc, open("server.json", "w", encoding="utf-8"), indent=2)
+          print(json.dumps(doc, indent=2))
+          PY
+      - name: install mcp-publisher
+        run: |
+          curl -fsSL -o mcp-publisher.tar.gz "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz"
+          echo "${MCP_PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum -c -
+          tar -xzf mcp-publisher.tar.gz mcp-publisher
+      - name: publish
+        run: |
+          ./mcp-publisher login github-oidc
+          ./mcp-publisher publish

procesio_cli-0.1.1/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.env
+.env.*
+*.local
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Per-user state: credentials profiles, environment registry, run history.
+# Never versioned - wiping this folder gives you a clean install.
+context-state-knowledge/
+
+# Local scratch.
+outputs/
+scratchpad/

procesio_cli-0.1.1/AGENTS.md

@@ -0,0 +1,17 @@
+# Agent instructions
+
+This repository's instructions for AI assistants live in **[CLAUDE.md](CLAUDE.md)**,
+including a generated capability router that maps a request to the exact command
+that serves it.
+
+Read that file first. It is not Claude-specific despite the name; the name is what
+several assistants look for by default, and duplicating the content here would give
+you two copies to drift apart.
+
+Quick orientation:
+
+```bash
+python scripts/list-tools.py                    # what is installed and configured
+python scripts/run-tool.py procesio --help      # the PROCESIO tool's actions
+python scripts/run-agent.py procesio guidance   # how to build and test properly
+```

procesio_cli-0.1.1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to PROCESIO CLI + Agent are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+This file is generated into the public repository from the PROCESIO monorepo; edit it
+there, not here.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-27
+
+### Changed
+- The Claude Code plugin moved to `plugin/`. It now installs the exact PyPI release
+  (`uvx --from procesio-cli==0.1.1`) instead of building the repository, ships four
+  skills and a listing icon, and no longer picks up the repository's agent docs as
+  subagents. The marketplace entry points at `./plugin`.
+- First release published to PyPI, so `pip install procesio-cli` and `uvx` work without a
+  clone.
+
+### Added
+- Each release attaches an MCPB bundle and is listed in the official MCP Registry as
+  `io.github.Procesio-Externals/procesio-cli`.
+
+## [0.1.0] - 2026-10-27
+
+First public release of PROCESIO CLI + Agent.
+
+### Added
+- The PROCESIO CLI: every platform API action as a subcommand, plus a generic `request`
+  for anything not wrapped.
+- A local MCP server, so an AI coding assistant can drive the platform over stdio.
+- Agent Skills carrying the build, verify and audit method.
+- Credentials in the operating system's secret store, never in a file.
+- Irreversible actions stop and ask before they run.

procesio_cli-0.1.1/CLAUDE.md

@@ -0,0 +1,115 @@
+# PROCESIO CLI + Agent
+
+Instructions for an AI assistant working in this repository. A human reader wants
+[README.md](README.md) instead.
+
+Command-line tooling and an AI agent for the PROCESIO automation platform: drive processes, forms, documents and custom actions from a terminal or from an AI coding assistant.
+
+## What this repo is
+
+A registry of **tools** and **agents** for the PROCESIO automation platform. A tool is
+a script that talks to PROCESIO. An agent carries method rather than mechanics: it
+drives tools and knows how the work should be done. Both are discovered from their
+manifests, so nothing anywhere holds a hardcoded list.
+
+```
+python scripts/list-tools.py                    # what exists, and whether it is ready
+python scripts/run-tool.py procesio --help      # every action and its arguments
+python scripts/run-agent.py procesio guidance   # the build-and-test playbook
+```
+
+The capability router at the bottom of this file maps a request to the command that
+serves it. It is generated from the manifests, so trust it over your memory of an
+earlier session.
+
+## The contract
+
+1. **JSON in, JSON out.** A tool prints exactly one JSON object on stdout for success,
+   or `{"error": {"code", "message", "details"}}` for failure, and exits non-zero on
+   failure. Progress and debug output go to stderr only. Never print anything else to
+   stdout: a caller is parsing it.
+2. **The manifest is the source of truth.** `tool.yaml` declares actions, arguments,
+   secrets and output. The registry reads manifests; everything else reads the
+   registry. Change the manifest in the same commit as the contract it describes.
+3. **Regenerate what is generated.** After a manifest change run
+   `python scripts/build-tool-skill.py <tool>` and `python scripts/build-router.py`.
+   A stale generated file is worse than a missing one, because it will be believed.
+4. **No secrets in files.** Ever. Credentials live in the OS credential store under
+   `agents-and-tools:<tool>:<secret>` and are read through `tools/_lib/creds.py`.
+   `python scripts/secret_scan.py` enforces this over the tree and refuses anything
+   credential-shaped. Never log, print or commit a secret value.
+5. **Framework and user data are separate.** `tools/`, `agents/` and `scripts/` are
+   shareable code and carry zero user-specific data. Everything about a particular
+   user or installation, including the environment registry and credential profiles,
+   lives under `context-state-knowledge/`, which is never versioned. Resolve those
+   paths through `tools/_lib/userdata.py`, never by hand.
+
+## Credentials
+
+Which store is used follows the platform, with no configuration: Windows Credential
+Manager, the macOS login Keychain, or the Linux desktop keyring. A headless machine
+has no OS keyring, so choose one explicitly with `AAT_CREDS_BACKEND`:
+`encrypted-file` (read/write, passphrase in `AAT_SECRETS_PASSPHRASE`), or `file` / `env`
+for secrets a host or cluster already manages. See `tools/_lib/README.md`.
+
+Store a credential with `python scripts/set-credential.py <tool> <secret>`. Never write
+one into a file, an argument, or a config, and never echo one back to the user.
+
+## Working on a PROCESIO process
+
+`tools/procesio/` holds the mechanics: the API client, the DTOs, the flow model, the
+canvas layout engine, and one handler per action. Its long-form notes
+(`PROCESIO-*-NOTES.md`) record non-obvious platform behaviour discovered the hard way,
+and they are the first place to look when the API does something surprising.
+
+`agents/procesio/` holds the method: the build-and-test playbook, the best practices,
+and the verify gate. Before building or changing a process, read
+`python scripts/run-agent.py procesio guidance`. Before calling one done, run
+`python scripts/run-agent.py procesio verify --process-id <id>` - a process that
+validates is not the same as a process that runs.
+
+## Adding a tool
+
+1. Create `tools/<name>/` with a `tool.yaml`, an entrypoint, and a `README.md`.
+2. Declare every secret under `secrets:`. The registry reports `missing_secrets` until
+   they are stored, which is how "not configured" stays distinct from "broken".
+3. Generate its manual: `python scripts/build-tool-skill.py <name>`.
+4. Confirm it appears in `python scripts/list-tools.py`.
+
+Write anything you learn about an external system into a durable note in that tool's
+own folder in the same session you learn it. A discovery that lives only in a chat is
+gone by the next one.
+
+## Capability Router (auto-generated)
+
+<!-- CAPABILITY-ROUTER:START — generated by scripts/build-router.py; rerun after adding/removing a tool. Do not hand-edit. -->
+
+### Tools — run with `python scripts/run-tool.py <tool> <action> [--args]`
+
+- **connector-builder** — build a PROCESIO custom action / connector from API docs; generate a .nupkg connector for PROCESIO from documentation; create / run / drive an AI Connector Builder build; approve / revise the plan / regenerate files / download the connector artifact; edit the connector builder's prompts / spec modules / examples (improve generation) → `connector-builder create-build --api-url <docs-url> --user-requirements '...'   (then gather / answer / approve-plan / approve-generate / download-artifact)`
+- **framework-map** — regenerate / rebuild the framework map or the agents-and-tools visualization; update the framework HTML with the new tools / agents / mechanics; refresh the agents and tools diagram / presentation page; which tools or agents changed / still need an RO translation; build the bilingual framework map (EN/RO) → `framework-map build   (dry-run counts + untranslated: framework-map check)`
+- **mysql** — run a MySQL query; query a MySQL / MariaDB database; read a table from MySQL; list MySQL tables or columns → `mysql query --profile default --sql "SELECT * FROM issues LIMIT 10"`
+- **procesio** — procesio; run a procesio process; launch procesio process; procesio workspace; procesio api; list procesio processes; procesio instance; trigger procesio flow; procesio endpoint; export procesio; procesio export; import procesio / import a .procesio bundle; duplicate a process / copy a process / clone a process; delete a process / form / document / webhook / credential; validate a process (correctness oracle); test a credential connection / test a custom action; upload / install / delete / list a custom action (.nupkg connector); download a flow-instance file (Generate-Document output); layout / re-lay-out a process canvas; read or inspect a flow graph; list forms / list documents; get or toggle a process; AI Decisional; switch procesio environment / work on PROCESIO Internal-QA / Internal-DEV / a client env; list / add / set the default procesio environment (<Client>-<ENV>); bind a credential to an environment; run procesio against QA / DEV / staging / a client installation → `procesio list-processes   (run: procesio run-process --id <id> --payload '{...}')`
+- **sqlserver** — run a SQL Server query; query a SQL Server / MSSQL database; read a table from SQL Server; list SQL Server tables or columns → `sqlserver query --profile default --sql "SELECT TOP 10 * FROM dbo.Customer"`
+- **web** — drive/scrape a website that has no API, using a saved login session; deeper web research → `web run --session <name> ...   (read text: web get-text; one-time login: web save-session)`
+- **xlsx** — Read local Excel (.xlsx/.xlsm) workbooks - list sheets, read a sheet as JSON, or dump the whole file to text → `xlsx list-sheets`
+
+### Agents — run with `python scripts/run-agent.py <agent> <action> [--args]`
+
+- **connector-builder** — build a PROCESIO custom action / connector from API docs and test it; drive the AI Connector Builder end to end (gather → plan → generate → compile); what's the next step for this connector build; upload a generated connector to PROCESIO and improve it from the feedback; how do I run the connector build → test → improve loop → `connector-builder next-step --build-id <ID>   (checklist: connector-builder checklist; guidance: connector-builder guidance --topic playbook; status: connector-builder status)`
+- **procesio** — build a procesio use case; test / verify a procesio process or resource; audit a procesio process for best practices; how should I build / test in procesio; improve a procesio implementation → `procesio verify --process-id <id>   (audit: procesio audit --process-id <id>; guidance: procesio guidance; checklist: procesio checklist)`
+
+### Skills
+
+Claude **auto-triggers** these from their descriptions — do NOT run-tool them. Project agents discover them via the registry and load one's full content with `python scripts/get-skill.py <name> --content`.
+
+**Registered in this project** — run `python scripts/list-skills.py` (`skills/<name>/`):
+
+- **agent-skill-engineer** — create, update, split, merge, refactor, or audit an Agent Skill or SKILL.md package; optimize skill descriptions, routing boundaries, progressive disclosure, context cost, or safety; design fixed-rubric skill evaluations, baselines, A/A noise checks, A/B comparisons, or field trials → `get-skill.py agent-skill-engineer`
+- **procesio-cli** — operate or troubleshoot a PROCESIO workspace through the CLI or MCP; create, edit, run, validate, audit, export, import, schedule, trigger, test, or verify a PROCESIO resource; inspect a PROCESIO process instance, form, document, webhook, credential, data model, or custom action → `get-skill.py procesio-cli`
+- **procesio-cli-maintainer** — change or review the procesio-cli repository source, manifests, tools, agents, MCP, registry, CI, or tests; add an action or capability while preserving JSON, credentials, routing, generation, and reversibility contracts; integrate an already-designed Agent Skill into repository generation, translations, governance, or release controls → `get-skill.py procesio-cli-maintainer`
+- **procesio-platform-advisor** — 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 → `get-skill.py procesio-platform-advisor`
+- **procesio-setup** — Connect this installation to a PROCESIO workspace, so the MCP server and the CLI can reach it → `get-skill.py procesio-setup`
+- **sql-server-optimizer** — analyze or optimize SQL Server T-SQL, execution plans, indexes, logical reads, blocking, or parameter sniffing; review SQL used in a PROCESIO Execute Query or Execute Command action; replace unsafe PROCESIO inline SQL variables with native typed parameters → `get-skill.py sql-server-optimizer`
+
+<!-- CAPABILITY-ROUTER:END -->