Autonomy CLI runbook — connector goals from the shell

Practical runbook: how Subactor turns a natural-language (NL) goal into governed URI Process steps, starting from the shell CLI. Focus example: documentation in the docs repo published to docs.subactor.com httpdocs.

Related (platform-internal, more detailed on single concerns):

1. Current state (what works)

Stack map

CLI entry points (start here)

# Founder control plane (needs live platform :8091)
ln -sfn ~/github/subactor/platform/bin/subactor ~/.local/bin/subactor
subactor health
subactor ask "zsynchronizuj www do httpdocs"          # LLM intent → ticket/plan
subactor ask "..." --execute                          # approve + execute
subactor ask "..." --autonomous <contract_id>         # within contract bounds
subactor tickets
subactor plans --status proposed
subactor dispatch

# Thin orchestrator (recipe-first; no OpenRouter key in this package)
cd ~/github/subactor/orchestrator
node bin/subactor-run.mjs --recipe ../www/deployment/www-httpdocs-sync.urirun.json
node bin/subactor-run.mjs --nl "zsynchronizuj www"    # phrase stub only
# Founder bypass: SUBACTOR_ADMIN_TOKEN set → human_approval skipped; still dry-run by default
# Live apply: --execute + PLESK_SYNC_APPLY=1 on urirun-node

What already works for publish

OpenRouter role today: intent / model selection / plan proposal only. Once URI + payload are known, FTP/SFTP ensure and sync are **deterministic connector calls** — no LLM in the upload path.

2. Gaps (better autonomy + subtask delegation)

3. Proposed model — NL only example

User says only:

„stwórz dokumentację w folderze docs i repo docs i opublikuj dokumentację
dla systemu subactor pod domeną docs.subactor.com”

Pipeline (target)

flowchart TD
  NL[NL shell: subactor ask / subactor-run] --> LLM[OpenRouter via llm-gateway]
  LLM --> Plan[Planfile ticket + uri_processes]
  Plan --> AQL[Contract AQL gate]
  AQL --> OQL[OQL process.run / plesk.*]
  OQL --> URI[urirun-node]
  URI --> Pre[Domain / subscription preflight]
  Pre --> Cred[ftpuser ensure → vault]
  Cred --> Content[LLM or human: docs content]
  Content --> Sync[plesk://…/sync dry-run then apply]
  Sync --> Verify[HTTPS verify docs.subactor.com]
  AQL -.->|out of contract| Human[human:founder ticket]

Ordered steps (current vs target)

4. Where the LLM participates vs deterministic steps

Rule: OpenRouter never holds FTP/SFTP passwords and never performs upload. Connectors read vault leases; apply requires explicit env gate.

5. USER vs SYSTEM — APIs / languages / CLIs

Start from the shell. Prefer deterministic CLIs when the URI is already known.

Languages / packages (no secrets in docs)

6. Concrete flow — docs → docs.subactor.com

Mirror of the proven www → subactor.com path, adapted for docs.

6.1 Preconditions

6.2 Target recipe shape (illustrative — no secrets)

{
  "id": "docs-httpdocs-sync",
  "name": "Sync docs → Plesk httpdocs (docs.subactor.com)",
  "situation": {
    "source_dir": "/home/tom/github/subactor/docs",
    "host": "prototypowanie.pl",
    "domain": "docs.subactor.com"
  },
  "uri_processes": [
    {
      "id": "docs-domain-preflight",
      "uri": "plesk://host/api/query/request",
      "payload": {"path": "/api/v2/domains"},
      "human_approval": false
    },
    {
      "id": "docs-sftp-ensure",
      "uri": "plesk://host/ftpuser/command/ensure",
      "payload": {
        "kind": "system",
        "domain": "docs.subactor.com",
        "vault_entry_id": "plesk-sftp"
      },
      "depends_on": ["docs-domain-preflight"],
      "human_approval": true
    },
    {
      "id": "docs-methods",
      "uri": "plesk://host/site/query/methods",
      "payload": {"host": "prototypowanie.pl"},
      "depends_on": ["docs-sftp-ensure"],
      "human_approval": false
    },
    {
      "id": "docs-sync-dry-run",
      "uri": "plesk://host/site/command/sync",
      "payload": {
        "source_dir": "/home/tom/github/subactor/docs",
        "remote_path": "/httpdocs",
        "host": "prototypowanie.pl",
        "domain": "docs.subactor.com",
        "apply": false
      },
      "depends_on": ["docs-methods"],
      "human_approval": false
    },
    {
      "id": "docs-sync-apply",
      "uri": "plesk://host/site/command/sync",
      "payload": {
        "source_dir": "/home/tom/github/subactor/docs",
        "remote_path": "/httpdocs",
        "host": "prototypowanie.pl",
        "domain": "docs.subactor.com",
        "apply": true
      },
      "depends_on": ["docs-sync-dry-run"],
      "human_approval": false
    }
  ]
}

Content generation (LLM) is a separate preceding ticket or plan step writing into the git repo — not an argument to sync.

6.3 Operator cheat sheet (today → tomorrow)

Today (www pattern, adapt manually for docs):

# 1) Prefer recipe without inventing URI
cd ~/github/subactor/orchestrator
node bin/subactor-run.mjs --recipe ../www/deployment/www-httpdocs-sync.urirun.json

# 2) Or founder NL → control (intent only)
subactor ask "zsynchronizuj www do httpdocs" --json

# 3) Live apply only after dry-run OK
# on urirun-node host: export PLESK_SYNC_APPLY=1
node bin/subactor-run.mjs --recipe ../www/deployment/www-httpdocs-sync.urirun.json --execute

Tomorrow (docs autonomy):

# NL (intent → multi-step ticket)
subactor ask "stwórz dokumentację w folderze docs i opublikuj na docs.subactor.com" \
  --autonomous <docs-publish-contract-id>

# Or deterministic
node bin/subactor-run.mjs --recipe ../docs/deployment/docs-httpdocs-sync.urirun.json
# content bot ticket completes first; then:
node bin/subactor-run.mjs --recipe ../docs/deployment/docs-httpdocs-sync.urirun.json --execute
curl -fsS -o /dev/null -w "%{http_code}\n" https://docs.subactor.com/

6.4 Allowlist / safety

7. Subtask delegation (autonomy pattern)

Use Planfile Respond + Delegate so note, assignee, queue, and status stay one history entry (see URI Process autonomy doc).

8. Implementation backlog (docs publish autonomy)

Ordered, small tickets — one concern each:

1. Allowlist docs (or prefix) for sync planner + connector.
2. Add docs/deployment/docs-httpdocs-sync.urirun.json + Planfile import.
3. Wire ftpuser/command/ensure as first step; vault id convention.
4. NL phrases + optional LLM model docs-httpdocs-sync.pl.aql.
5. Optional content-generation ticket template (LLM → files → commit).
6. Post-apply HTTPS verify step / TestQL scenario.
7. Contract portfolio entry for docs publish (human-signed).

9. Quick reference — OpenRouter vs connectors

Canonical path: docs/autonomy-cli-runbook.md (this file). Umbrella link: repo root README.md.