gemstone-nexus · Phase 6

DIDYMUS-PLAYBOOK — Practitioner Provisioning and Queue Ops

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
3DIDYMUS-PLAYBOOKDIDYMUS-PLAYBOOK — Practitioner Provisioning and Queue OpsplaybookDevResources/docs/DIDYMUS-PLAYBOOK.mdOperator and practitioner guide for provisioning AI development-tool workers, storing credentials in the secrets tier, registering workers with Didymus, and running the human approval queue. Architecture detail is in DIDYMUS-ARCH-01; this playbook is the how-to companion.6ba9fd6e1ea95ec0450198a03a25f83213d6faa32026-07-22 18:33:18

Content

# DIDYMUS-PLAYBOOK — Practitioner Provisioning and Queue Ops

*Install, authorize, and operate Didymus AI workers through GemStone*

**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Phase 3C Implemented · **Date:** July 21, 2026

## 1. Purpose

Operator and practitioner guide for provisioning AI development-tool workers, storing credentials in the secrets tier, registering workers with Didymus, and running the human approval queue. Architecture detail is in DIDYMUS-ARCH-01; this playbook is the how-to companion.

## 2. Preconditions

- Auth0 roles available: SuperAdmin, Org Admin, Practitioner (approvers); GemStone Agent may submit only (never approve).
- Secrets tier ready: AWS Secrets Manager secret `DATARIGHT_DEV_SECRETS` (us-east-1) on GoldenAMI / EC2, **or** host `.env` injected into `gemstone-api` on the clean local FullBase clone. **Never commit secrets to the repo.**
- Didymus runs in-process with GemStone API at Phase 3C (`DIDYMUS_HUB_URL` optional for a future external split; leave unset on the T4 host).
- GemStone approval queue UI: `/app/didymus` (Capacitor + web).

## 3. Provision Workers (MVP)

For each of **Cursor**, **Claude**, and **Gemini** (optional sovereign **Ollama**):

1. Create or identify the vendor account under the practitioner or org billing owner.
2. Generate the API key, PAT, or OAuth client secret required by that worker.
3. Store the secret in AWS Secrets Manager / host env under these exact keys (no repo files):

| Worker | Env key(s) | Where to place |
| --- | --- | --- |
| Cursor | `DIDYMUS_WORKER_CURSOR_TOKEN` | `DATARIGHT_DEV_SECRETS` JSON field or compose `environment:` on `gemstone-api` |
| Claude | `DIDYMUS_WORKER_CLAUDE_API_KEY` | same |
| Gemini | `DIDYMUS_WORKER_GEMINI_API_KEY` (fallback: existing `GEMINI_API_KEY`) | same |
| Ollama (optional) | `DIDYMUS_WORKER_OLLAMA_ENDPOINT` | e.g. `http://gemstone-ollama:11434` — omit to use simulated/local default |

4. Confirm the API container can read the key at process start (`docker exec gemstone-api printenv DIDYMUS_WORKER_CLAUDE_API_KEY` should print a non-empty value when provisioned). Values must never appear in task payloads, logs, or MCP arguments.
5. Install/authorize the worker runtime on the intended machine (Cursor IDE agent, Claude tooling, Gemini tooling, or Ollama service). Phase 3C hub workers implement `get_capabilities` / `execute_command` / `report_status` / `verify_output`; live vendor calls run when a matching **vault** key or host env key is present — otherwise execute is **simulated** so gates pass on sovereign hosts.

### 3.0 Practitioner vault (preferred for live execute)

1. Ensure host `.env` (never git) has `WORKER_SECRETS_KEY` (32-byte value, base64). Without it `GET /api/didymus/workers/credentials` reports `vault_available: false` and Connect in the UI will fail closed.
2. Sign in (local login when enabled) or use SuperAdmin/dev principal, open **`/app/onboarding/workers`**, Connect Cursor / Claude / Gemini keys. Values are AES-GCM sealed in `worker_credentials` (last-4 only returned).
3. Host env fallbacks (`DIDYMUS_WORKER_*` / `GEMINI_API_KEY`) still work for operators; Gemini Live voice key satisfies Gemini worker `credential_configured` when vault empty.
4. Confirm `GET /api/didymus/workers` / credentials show `configured: true`. Live path: approve → lease → `POST .../execute` with `worker_id` → `result.mode` is `live` or `simulated`.

### 3.1 Secrets placement (EC2 T4 / OD)

```text
# Preferred: merge keys into DATARIGHT_DEV_SECRETS (us-east-1), then restart api
# so app.core.secrets.load_aws_application_secrets picks them up.

# Alternate: host override file (not git-tracked), e.g. /home/dr/AppDev/gemstone-nexus/.env.didymus
DIDYMUS_WORKER_CURSOR_TOKEN=...
DIDYMUS_WORKER_CLAUDE_API_KEY=...
DIDYMUS_WORKER_GEMINI_API_KEY=...
```

Wire overrides into compose via an untracked env file or `environment:` block — do not add them to committed `docker-compose.yml` with real values.

### 3.2 Practitioner checklist (accounts)

1. **Cursor** — Settings → API / Account → create PAT with agent scopes; store as `DIDYMUS_WORKER_CURSOR_TOKEN`.
2. **Claude** — Anthropic Console → API Keys → create key; store as `DIDYMUS_WORKER_CLAUDE_API_KEY`.
3. **Gemini** — Google AI Studio / Cloud → API key; store as `DIDYMUS_WORKER_GEMINI_API_KEY` (or reuse stack `GEMINI_API_KEY` if already present for voice).
4. Confirm `GET /api/didymus/workers` shows `credential_configured: true` for each provisioned worker.

## 4. Register a Worker

MVP workers (`cursor`, `claude`, `gemini`) auto-seed into `didymus_workers` for the default org on API startup.

Manual / additional registration:

```bash
curl -sS -X POST "http://127.0.0.1:8000/api/didymus/workers/register" \
  -H "Content-Type: application/json" \
  -H "X-Org-Id: 00000000-0000-4000-8000-000000000001" \
  -d '{
    "worker_id": "cursor",
    "family": "cursor",
    "display_name": "Cursor",
    "task_types": ["code_edit", "refactor", "generic"],
    "max_concurrency": 1,
    "tier_affinity": "any"
  }'
```

Or MCP: workers call `get_capabilities()` locally; hub stores the row via register. Map High Security workers so they do not call cloud-only paths (`tier_affinity` advisory at Phase 3C).

Verify:

```bash
curl -sS "http://127.0.0.1:8000/api/didymus/workers" -H "X-Org-Id: <org>"
```

Record registration in the Project Ledger (deploy note) without secret values.

## 5. Submit and Approve Tasks

1. Worker or GemStone Agent submits:
   - REST: `POST /api/didymus/tasks` `{requested_by, target_worker, task_type, payload}` → `PENDING`
   - MCP: `POST /mcp/didymus/submit_task`
2. Approver opens **`/app/didymus`**. Default cards are identical (blind-source). Audit metadata is behind an explicit expand — never used for color/badge styling.
3. Approver confirms intent → Approve → `approved_by` + `approved_at` set, status `APPROVED`.
4. Worker leases: `POST /api/didymus/tasks/{id}/lease` → `RUNNING`. `PENDING → RUNNING` returns **409**. Direct SQL/API force without approval fields hits **`didymus_tasks_approval_gate`** (schema CHECK).
5. Worker reports: `POST .../report` → `COMPLETED` | `FAILED`; verify → `VERIFIED`.
6. If a task ever reaches RUNNING without approval fields, execute DOC08 Section 3 immediately.

### 5.1 Example submit (three MVP sources)

```bash
ORG=00000000-0000-4000-8000-000000000001
for pair in "cursor-agent|cursor" "claude-agent|claude" "gemini-agent|gemini"; do
  IFS='|' read -r BY W <<< "$pair"
  curl -sS -X POST "http://127.0.0.1:8000/api/didymus/tasks" \
    -H "Content-Type: application/json" -H "X-Org-Id: $ORG" \
    -d "{\"requested_by\":\"$BY\",\"target_worker\":\"$W\",\"task_type\":\"generic\",\"title\":\"Example from $W\",\"payload\":{\"summary\":\"Example from $W\"},\"org_id\":\"$ORG\"}"
done
```

## 6. Approval Queue Ops Checklist

| Check | Pass criteria |
| --- | --- |
| Queue freshness | PENDING items visible within seconds of submit (`GET /api/didymus/tasks`) |
| Org isolation | Approver never sees another org's tasks (RLS + `X-Org-Id`) |
| Blind source | No origin badge/color in default view; `presentation.kind` always `didymus_task` |
| Audit | Expand shows `requested_by` / `target_worker` without styling |
| Schema gate | `POST .../force-running` returns `rejected: true, by: schema_constraint` |
| Reject / leave PENDING | Leaving PENDING is safe; no auto-escalate to RUNNING |

Gate script on host: `bash scripts/phase3c-gates.sh` (requires `gemstone-api` container).

## 7. Credential Rotation

1. Generate new secret at vendor.
2. Update secrets tier first; restart `gemstone-api` (and any external worker process) to pick up the new value.
3. Revoke the old secret at vendor.
4. Confirm `credential_configured: true` and a no-op lease/heartbeat still succeeds.
5. Log rotation in the Project Ledger without recording secret values.

## 8. Local vs Primary Env Notes

- Primary: T4 GoldenAMI EC2 `i-04333dae160ab0daa` / `18.116.188.14` (production-like secrets via AWS Secrets Manager).
- Local secondary: clean clone from `DataRightGoldenOVAFullBase` only; use host env / local secrets file, never the retired `10.0.0.210` GemStone VM.
- Disk on T4 is tight (~3.5G free typical after Whisper CUDA) — prune carefully; keep Whisper CUDA images/models.
- Social login testing (Google, Facebook, LinkedIn) uses the Auth0 tenant shared with the app; do not embed social app secrets in the mobile binary beyond Auth0 client config.

## 9. Auth0 Tenant Provisioning (practitioner checklist)

**Do not invent or commit tenant credentials.** Placeholders (`AUTH0_*` / `VITE_AUTH0_*`) keep the stack bootable with `configured:false` on `/healthz` until a real tenant exists.

### 9.1 Create the Auth0 application

1. In the Auth0 dashboard, create (or select) a tenant for GemStone / NEXTECH.
2. Create a **Regular Web Application** for the Vite/Capacitor SPA (and optionally a Native app for store builds later).
3. Note **Domain**, **Client ID**, and (server-only) **Client Secret**. Never commit the secret; store it in AWS Secrets Manager / host `.env`.
4. Set **Allowed Callback URLs** to include:
   - `https://<host>/app/login`
   - Capacitor deep links when native builds are ready (`com.nextech.gemstone://...`)
5. Set **Allowed Logout URLs** and **Allowed Web Origins** to the same host origins (`https://<host>`, `https://<host>/app`).
6. Enable **Universal Login**. Connect social IdPs: Google, Facebook, LinkedIn (each requires its own vendor OAuth app; store those secrets in Auth0, not in this repo).

### 9.2 API / audience

1. Create an Auth0 **API** with identifier/audience matching `AUTH0_AUDIENCE` (e.g. `https://gemstone.dataright.net/api`).
2. Map roles per DOC03 Section 7: **SuperAdmin**, **Org Admin**, **Practitioner**, **GemStone Agent** (Auth0 Actions or Role claim).
3. Prefer org tenancy via Auth0 Organizations (`auth0_org_id` on `orgs`) when enabling multi-tenant login.

### 9.3 Wire into GemStone (after values exist)

1. Set host secrets (never git):
   - `AUTH0_DOMAIN`, `AUTH0_AUDIENCE`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `AUTH0_ISSUER`, `AUTH0_ENABLED=true`
   - `VITE_AUTH0_DOMAIN`, `VITE_AUTH0_CLIENT_ID` (rebuild `web` image after changing Vite args)
2. Redeploy: `.\scripts\run-remote-docker-deploy.ps1`
3. Confirm `/healthz` → `checks.auth0.configured: true` and login at `/app/login` reaches Universal Login.
4. Record completion in the Project Ledger (decision/deploy note) without secret values.

### 9.4 UX reference

Login layout target remains **HorizonORBIT** from the **HorizonCRM** repo. Keep the Auth0 stub shell until HorizonCRM is cloned and the layout is ported under DataRightTailwind.

## 10. Out of Scope

- Desktop SolidWorks / KiCad workers (DOC02 Section 3).
- Autonomous execution of any task category.
- Storing credentials in git, Capacitor bundled assets, or Didymus task JSON.
- Claude Code / AntiGravity / GemStone-as-worker runtime (deferred until three-worker MVP stable 30+ days).


---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505