@dezycro-ai/agent-plugin 2.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "dezycro",
+  "version": "2.0.0",
+  "description": "Dezycro AI plugin — reverse-engineer your codebase into features, PRDs, TRDs, and test cases. Companion V2 adds proactive verify gates, auto-publish-spec nudges, and a guided PRD/TRD authoring flow.",
+  "homepage": "https://dezycro.ai",
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Dezycro Inc. All rights reserved.
+
+This software and its source code are proprietary and confidential to
+Dezycro Inc. No part of this software may be reproduced, distributed,
+modified, sublicensed, or used to create derivative works, in whole or
+in part, without the prior written permission of Dezycro Inc.
+
+The software is provided to authorized users solely for use with the
+Dezycro platform under the terms of a separate agreement. Unauthorized
+copying, distribution, reverse engineering, decompilation, or
+disassembly is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL DEZYCRO INC. BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/PERSONAS.md

@@ -0,0 +1,309 @@
+# Persona Auth Configuration
+
+The Dezycro verifier runs generated tests against your API using **personas** — named users with different permission levels (e.g., `admin1`, `user1`, `readonly1`). Each persona needs credentials. This document describes how to configure them locally so `/dezycro:verify` can obtain tokens and run tests against a real, authenticated API.
+
+## TL;DR
+
+```bash
+# 1. Run /dezycro:init — it will detect your project's personas
+#    and prompt you to configure credentials for each.
+#
+# 2. Secrets live at ~/.dezycro/secrets/<name> (chmod 600),
+#    NOT inside the repo.
+#
+# 3. The repo-local .dezycro/auth.local.json is gitignored
+#    and references those secret files via !file: pointers.
+#
+# 4. /dezycro:verify reads auth.local.json, resolves secrets,
+#    exports the right env vars, then invokes the verifier binary.
+```
+
+## Why this exists
+
+The verifier binary is a self-contained Go executable with an embedded `AUTH_CONFIG`. The config maps each persona name to an environment variable name, e.g.:
+
+```json
+{
+  "authenticators": {
+    "admin1": { "type": "http_endpoint", "envVar": "AUTH_ADMIN1" },
+    "user1":  { "type": "http_endpoint", "envVar": "AUTH_USER1" }
+  }
+}
+```
+
+When the binary runs a test that needs authentication, it:
+1. Looks up the persona (`admin1`).
+2. Reads the env var the config points at (`AUTH_ADMIN1`).
+3. Expects that env var to contain a **JSON configuration** telling it how to obtain a token.
+4. For `http_endpoint` type, it calls the configured endpoint, extracts the token, caches it, and adds it to requests.
+
+CI populates those env vars from whatever secret store your pipeline uses (GitHub Actions secrets, GitLab CI variables, etc.). Locally, there is no equivalent. This doc describes how `/dezycro:init` and `/dezycro:verify` close that gap without committing secrets to the repo.
+
+## The three files
+
+| File | Location | Purpose | Committed? |
+|---|---|---|---|
+| `.dezycro/config.json` | repo | Project-wide config (workspace/project IDs, environments) | ✅ yes |
+| `.dezycro/auth.local.json` | repo | Per-persona auth config, with secrets as `!file:` or `${VAR}` references | ❌ gitignored |
+| `~/.dezycro/secrets/<name>` | home | Raw secret values (passwords, client_secrets) | ❌ outside repo |
+
+`/dezycro:init` creates and maintains the first two. You manage `~/.dezycro/secrets/` yourself (or replace with `pass`, `op`, a vault, etc — see [Secret backends](#secret-backends)).
+
+## `auth.local.json` schema
+
+```json
+{
+  "version": 1,
+  "personas": {
+    "<persona-name>": {
+      "envVar": "<env-var-name>",
+      "config": { /* verifier auth config, shape depends on "type" */ }
+    }
+  },
+  "secrets": {
+    "<token-name>": "<value or !file: or ${VAR}>"
+  }
+}
+```
+
+### Top-level keys
+
+| Key | Type | Required | Description |
+|---|---|---|---|
+| `version` | integer | ✅ | Schema version. Current: `1`. Older verifiers accept lower versions; newer verifiers may ignore unknown fields. |
+| `personas` | object | ✅ | Map of persona name → auth config. Persona names must match those defined on the personas of your Dezycro project. |
+| `secrets` | object | optional | Named secret pool. Used for `${TOKEN_NAME}` placeholders inside `personas[].config`. |
+
+### `personas[name]` entry
+
+| Key | Type | Required | Description |
+|---|---|---|---|
+| `envVar` | string | ✅ | Name of the environment variable the verifier binary expects. Must match the `envVar` configured on that persona in Dezycro. Pattern: `AUTH_*`. |
+| `config` | object | ✅ | Verifier auth config JSON. Shape depends on the persona's `type` (see per-type sections below). This object is serialized to JSON and assigned to the env var before the binary runs. |
+| `type` | string | optional | Optional echo of the persona's type (`bearer`, `basic`, `header`, `http_endpoint`, `js`, `none`). Purely informational for humans reading this file — the verifier learns the type from its embedded `AUTH_CONFIG`, not from here. |
+
+### `secrets[name]` entry
+
+Values may be:
+
+- **Inline literal**: any string that doesn't start with `!` or `${` is used verbatim. Avoid for real secrets.
+- **File reference**: `!file:<path>` — read the secret from that file. `~` is expanded to `$HOME`. Environment variables are **not** expanded in the path.
+- **Env-var reference**: `!env:<NAME>` — read from process environment. Useful for CI parity and 1Password CLI (`op run`) integration.
+- **Command reference**: `!cmd:<command>` — execute command and use stdout (trimmed). For `pass`, `gopass`, `op read`, `security find-generic-password`, etc.
+
+Placeholders in `personas[].config` are substituted **after** secrets are resolved. Placeholder syntax: `${SECRET_NAME}`. Substitution is recursive one level deep (a secret value is not itself substituted).
+
+## Auth types and their `config` shapes
+
+### `bearer`
+Simple static bearer token.
+
+```json
+{
+  "envVar": "AUTH_SERVICE_ACCOUNT",
+  "config": { "token": "${SERVICE_ACCOUNT_TOKEN}" }
+}
+```
+
+Verifier sends: `Authorization: Bearer <token>`.
+
+### `basic`
+HTTP Basic auth.
+
+```json
+{
+  "envVar": "AUTH_CI_USER",
+  "config": { "username": "ci-bot", "password": "${CI_BOT_PASSWORD}" }
+}
+```
+
+Verifier sends: `Authorization: Basic <base64(username:password)>`.
+
+### `header`
+Arbitrary static headers. Use for API keys, signed tokens, or multi-header auth.
+
+```json
+{
+  "envVar": "AUTH_API_KEY",
+  "config": {
+    "headers": {
+      "X-API-Key":   "${API_KEY}",
+      "X-Client-Id": "my-app"
+    }
+  }
+}
+```
+
+Verifier merges `headers` into every request.
+
+### `http_endpoint` (most common for dev)
+Call an auth service to obtain a token. Used for OAuth2 password grant, OIDC token endpoints, custom dev login routes, etc.
+
+```json
+{
+  "envVar": "AUTH_ADMIN1",
+  "config": {
+    "url":          "https://auth.example.com/oauth/v2/token",
+    "method":       "POST",
+    "headers":      { "Content-Type": "application/x-www-form-urlencoded" },
+    "body":         "grant_type=password&client_id=${OAUTH_CLIENT_ID}&username=admin1@example.com&password=${ADMIN1_PASSWORD}",
+    "tokenPath":    "access_token",
+    "headerName":   "Authorization",
+    "headerPrefix": "Bearer "
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `url` | — (required) | Token endpoint. |
+| `method` | `"POST"` | HTTP method. |
+| `headers` | `{}` | Request headers. Host override supported via `"Host": "..."` — useful when calling an internal service whose vhost differs from its DNS name. |
+| `body` | `""` | Request body. URL-encoded form or JSON — whatever the endpoint expects. |
+| `tokenPath` | `"access_token"` | JSON field name in the response body holding the token. |
+| `headerName` | `"Authorization"` | Response header on test requests. |
+| `headerPrefix` | `"Bearer "` | Prefix for the header value (mind the trailing space). |
+
+The verifier caches the response per persona for the lifetime of the run, so the endpoint is called at most once per persona per run.
+
+### `js`
+Custom JavaScript for exotic auth (request signing, TOTP, MFA). The script receives a `process.env` object with filtered env vars (`AUTH_*`, `API_*`, `DEZYCRO_*`) plus any fields inside `config`, and must return `{ headers: { ... } }`.
+
+```json
+{
+  "envVar": "AUTH_HMAC",
+  "config": {
+    "accessKey": "${HMAC_ACCESS_KEY}",
+    "secret":    "${HMAC_SECRET}"
+  }
+}
+```
+
+The `script` itself is compiled into the verifier binary (configured in Dezycro). Don't put it in `auth.local.json`.
+
+### `none`
+No auth headers. Explicit documentation that a persona deliberately goes unauthenticated (e.g., anonymous user testing public endpoints). No `config` needed:
+
+```json
+{ "envVar": "AUTH_ANON", "config": {} }
+```
+
+## Complete example
+
+```json
+{
+  "version": 1,
+  "personas": {
+    "admin1": {
+      "envVar": "AUTH_ADMIN1",
+      "type":   "http_endpoint",
+      "config": {
+        "url":    "https://auth.example.com/oauth/v2/token",
+        "method": "POST",
+        "headers": { "Content-Type": "application/x-www-form-urlencoded" },
+        "body":   "grant_type=password&client_id=${OAUTH_CLIENT_ID}&username=admin1@example.com&password=${ADMIN1_PASSWORD}"
+      }
+    },
+    "user1": {
+      "envVar": "AUTH_USER1",
+      "type":   "http_endpoint",
+      "config": {
+        "url":    "https://auth.example.com/oauth/v2/token",
+        "method": "POST",
+        "headers": { "Content-Type": "application/x-www-form-urlencoded" },
+        "body":   "grant_type=password&client_id=${OAUTH_CLIENT_ID}&username=user1@example.com&password=${USER1_PASSWORD}"
+      }
+    },
+    "readonly1": {
+      "envVar": "AUTH_READONLY1",
+      "type":   "bearer",
+      "config": { "token": "${READONLY_PAT}" }
+    }
+  },
+  "secrets": {
+    "OAUTH_CLIENT_ID":    "!file:~/.dezycro/secrets/oauth_client_id",
+    "ADMIN1_PASSWORD":    "!file:~/.dezycro/secrets/admin1",
+    "USER1_PASSWORD":     "!cmd:op read op://Private/MyApp/user1/password",
+    "READONLY_PAT":       "!env:DEZYCRO_READONLY_PAT"
+  }
+}
+```
+
+## `/dezycro:init` behavior
+
+`/dezycro:init` is re-runnable. Each run:
+
+1. Writes/updates `.dezycro/config.json` (workspace + project binding).
+2. Fetches personas for the active project via the Dezycro API.
+3. For each persona that is **not already** in `auth.local.json`:
+   - Prints the persona name, type, and description.
+   - Prompts for the minimum needed — usually a secret name to reference and a path for its value.
+   - Writes the persona block to `auth.local.json`.
+   - Creates `~/.dezycro/secrets/<name>` with `chmod 600` if the user supplied a value; skips if they said they'll fill it in later.
+4. Ensures the repo `.gitignore` excludes `.dezycro/auth.local.json`.
+
+It never overwrites an existing persona entry. To reconfigure, delete the entry and re-run.
+
+## `/dezycro:verify` behavior
+
+Before invoking the verifier binary, `/dezycro:verify`:
+
+1. Loads `.dezycro/auth.local.json` (optional — missing file is fine, but authenticated tests will fail).
+2. Resolves every `secrets[*]` value (`!file:`, `!env:`, `!cmd:` — first error aborts).
+3. Substitutes `${NAME}` placeholders inside each `personas[*].config`.
+4. `json.Marshal`s the resolved config and `export`s it as the named env var.
+5. Runs the binary. The binary picks up the env vars via its embedded `AUTH_CONFIG`.
+6. Unsets the env vars after the run (they never land in shell history or parent process env).
+
+If a persona's env var can't be resolved, the skill prints a warning naming that persona and continues — tests that don't need that persona still run. Tests that do need it fail with `authenticator '<name>' not configured`.
+
+## Secret backends
+
+Pick whatever you already use:
+
+| Backend | Example secret value |
+|---|---|
+| Plain file | `!file:~/.dezycro/secrets/admin1` |
+| Process env | `!env:ADMIN1_PASSWORD` |
+| 1Password CLI | `!cmd:op read op://Private/MyApp/admin1/password` |
+| `pass` | `!cmd:pass show myapp/admin1` |
+| `gopass` | `!cmd:gopass show -o myapp/admin1` |
+| macOS Keychain | `!cmd:security find-generic-password -a $USER -s myapp-admin1 -w` |
+| GCP Secret Manager | `!cmd:gcloud secrets versions access latest --secret=myapp-admin1` |
+
+For `!cmd:`, the shell is `/bin/sh -c`, output is stripped of trailing whitespace, and a non-zero exit or empty stdout is treated as an error.
+
+## Gitignore
+
+`/dezycro:init` adds the following lines to the repo's `.gitignore` (idempotent — appends only if missing):
+
+```
+# Dezycro — local-only, never commit
+.dezycro/auth.local.json
+.dezycro/bin/
+```
+
+`.dezycro/bin/` is where cached verifier binaries live — also gitignored because they are large and content-hash-addressed.
+
+## Non-goals
+
+Deliberately out of scope for this local-dev flow:
+
+- **No token vault** — we don't build a secret store. Bring your own.
+- **No per-environment personas** (yet) — a single `auth.local.json` covers whichever environment `/dezycro:verify --env <name>` is pointed at. When two environments need genuinely different credentials, we'll add `.dezycro/auth.local.<env>.json`. File an issue when you hit this.
+- **No automatic credential rotation** — if a stored password expires, edit the secret file.
+- **No CI usage** — CI continues to read secrets from your pipeline's native secret store and export them as env vars directly. `auth.local.json` is a developer-ergonomic layer; production still exports `AUTH_*` from the platform's native secret store.
+
+## Troubleshooting
+
+**`authenticator 'admin1' not configured (check AUTH_CONFIG_admin1 env var)`**
+The binary couldn't find the env var named by its embedded `AUTH_CONFIG`. Check that `auth.local.json` has a `personas.admin1.envVar` matching what the binary expects (usually `AUTH_ADMIN1`), and that every `${…}` placeholder in its `config` resolved. Run `dezycro-verify doctor` to see what authenticators the binary knows about.
+
+**`token endpoint returned status 401`**
+The `http_endpoint` auth call itself failed. Double-check the request body (grant type, client id, credentials). Reproduce with `curl -d '<body>' '<url>'` using the resolved values.
+
+**`token field 'access_token' not found or empty in response`**
+`tokenPath` is wrong. Use `curl` to inspect the response shape and adjust.
+
+**Secrets leak into logs**
+They shouldn't — the skill logs only persona names and env-var names, never values. If you see a value, please file an issue.

package/README.md

@@ -0,0 +1,125 @@
+# Dezycro for AI coding agents
+
+> Turn any codebase into a documented, testable product — from your terminal.
+
+`@dezycro-ai/agent-plugin` is the official [Dezycro](https://dezycro.ai) plugin for AI coding agents — starting with [Claude Code](https://claude.com/claude-code), with more agents on the way. It plugs your agent into the Dezycro platform so you can reverse-engineer an existing codebase into a tree of **features**, each with a user-facing **PRD**, a matching technical **TRD**, generated **test cases**, and live **verification** runs — all without leaving your editor.
+
+You can drive everything by typing `/dezycro:*` slash commands, or just describe what you want in natural language and your agent will pick the right one.
+
+---
+
+## What you get
+
+| Surface | What it does |
+|---|---|
+| **`/dezycro:import-features`** | Scans your repo and proposes a tree of user-facing features with PRDs and TRDs. |
+| **`/dezycro:init`** | One-time per-repo setup. Binds the working directory to a workspace + project, writes `.dezycro/config.json`, and helps you wire up persona credentials. |
+| **`/dezycro:work [feature]`** | Loads a feature's full context (PRD, TRD, workbook, journeys, open tasks/issues) and makes it the active feature for the session. |
+| **`/dezycro:status`** | Compact summary of the active feature — journeys, tasks, issues, latest verification. |
+| **`/dezycro:sync`** | Reviews work done since you started, records decisions, opens tasks/issues, links commits in the workbook. |
+| **`/dezycro:publish-spec`** | Detects and uploads your OpenAPI spec for the active feature; triggers JEP (journey execution plan) generation. |
+| **`/dezycro:verify [--env]`** | Pulls the latest verifier binary, runs generated tests against the configured environment, and uploads results to the workbook. |
+| **Companion** | Background guardrails that block tasks from going to DONE without recent passing verifier evidence, nudge you to re-publish your OpenAPI spec when you touch a controller, and surface coverage gaps before you push. |
+
+Together, the plugin lets a single developer keep a project's product documentation, technical documentation, test coverage, and verification status all in sync with the code — incrementally, as they work.
+
+---
+
+## Install
+
+```bash
+npm install -g @dezycro-ai/agent-plugin
+```
+
+Full installation guide — prerequisites, MCP setup, troubleshooting, uninstalling — lives in the docs:
+
+**→ [docs.dezycro.ai/claude-code/install](https://docs.dezycro.ai/claude-code/install/)**
+
+---
+
+## Quick start
+
+The first run on a new repo is always the same three commands:
+
+```bash
+cd path/to/your-repo
+
+# In Claude Code:
+/dezycro:init               # bind this repo to a workspace + project
+/dezycro:import-features    # reverse-engineer the code into features + PRDs + TRDs
+/dezycro:work <feature>     # pick a feature and start working on it
+```
+
+After that, the inner loop while coding is:
+
+```bash
+/dezycro:status             # what's open, what's tracked
+/dezycro:sync               # push decisions/tasks/commits up to the workbook
+/dezycro:verify             # run the latest tests against your environment
+```
+
+You don't have to memorize the names — typing things like *"sync my work to Dezycro"* or *"verify this feature against staging"* will land on the right command.
+
+---
+
+## Commands
+
+### `/dezycro:init`
+
+One-time per-repo setup. Connects this working directory to a Dezycro workspace and project, detects the dev environment from your code (base URL, OpenAPI spec path, auth flow), writes `.dezycro/config.json`, and walks you through configuring credentials for any personas the project defines (`admin1`, `user1`, etc).
+
+Re-runnable — won't overwrite existing configuration, just fills gaps.
+
+### `/dezycro:import-features`
+
+Scans the codebase (frontend routes, backend controllers, jobs, integrations), groups what it finds into **user-facing features**, proposes a directory tree, asks for your approval, then creates the features and writes a PRD for each one based purely on user behavior — not on implementation details. After PRDs land, it can optionally trigger TRD and test-case generation for the same features.
+
+The PRDs read like product specs, not code summaries. The TRDs link back to the PRDs and document the implementation.
+
+### `/dezycro:work [feature-name-or-uuid]`
+
+Loads everything the agent needs to safely work on a feature: PRD, TRD, approved journey graph, JEP, recent verifier runs, open issues and tasks. **Gates on PRD + TRD completion and approved graph** — refuses to start on a feature that isn't ready. Without an argument, it lists features and lets you pick interactively.
+
+### `/dezycro:status`
+
+Compact one-screen summary of the active feature: journeys (and which are confirmed), open and resolved issues, open tasks with assignees, latest verifier run, blockers. Useful as a "where am I" check after a context reset.
+
+### `/dezycro:sync`
+
+The "checkpoint" command. Reviews what happened in the session — files touched, decisions made, problems encountered — and writes that back to the workbook. Idempotent: re-running won't duplicate entries.
+
+Run periodically while developing. PMs see the workbook update in near real time.
+
+### `/dezycro:publish-spec`
+
+Auto-detects your project's OpenAPI spec (Spring's `/v3/api-docs`, FastAPI's `/openapi.json`, a checked-in YAML, etc), optionally filters it to the active feature's endpoints, and uploads it. The upload triggers JEP generation in Dezycro — turning the spec into journey execution plans that drive test generation.
+
+### `/dezycro:verify [--env <name>]`
+
+Pulls the latest verifier binary for the active feature, resolves persona credentials, runs it against the chosen environment, and uploads the resulting step traces and assertion results to the workbook.
+
+Pass `--env staging` to target a non-default environment.
+
+---
+
+## Persona auth (for `/dezycro:verify`)
+
+When `/dezycro:verify` calls authenticated endpoints, it needs credentials for the personas your project defines (`admin1`, `user1`, `readonly1`, …). Configuration lives in `.dezycro/auth.local.json` — **always gitignored** — and references real secrets via files, env vars, `op read`, `pass show`, etc.
+
+See **[PERSONAS.md](./PERSONAS.md)** for the full schema, all supported auth types, every supported secret backend, and troubleshooting.
+
+`/dezycro:init` walks you through setting this up the first time; you rarely need to hand-edit `auth.local.json`.
+
+---
+
+## Support & troubleshooting
+
+For installation issues, MCP setup, updates, and uninstall instructions, see the [installation guide](https://docs.dezycro.ai/claude-code/install/).
+
+For everything else, sign in at [app.dezycro.ai](https://app.dezycro.ai) and use the in-app support channel.
+
+---
+
+## License
+
+Proprietary. Copyright © 2026 Dezycro Inc. All rights reserved. See [LICENSE](./LICENSE).

package/bin/resolve-auth.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// Resolve .dezycro/auth.local.json into a shell-safe env fragment suitable for
+// `env $(dezycro-resolve-auth) <verifier-binary> ...`.
+//
+// Schema is documented in claude-plugin/PERSONAS.md:
+//   personas.<name>.envVar  → env var name to set (e.g. AUTH_ADMIN1)
+//   personas.<name>.config  → JSON payload (the value of the env var)
+//   secrets.<NAME>          → secret pool used by ${NAME} substitution
+//     values may be:
+//       inline literal
+//       "!file:<path>"    — read file contents (~ expanded)
+//       "!env:<NAME>"     — read from process env
+//       "!cmd:<command>"  — run via /bin/sh -c, use trimmed stdout
+//
+// Missing file → exit 0 with empty output (not an error: CI/dev may export
+// the AUTH_* vars directly). Per-persona failures emit a stderr warning and
+// skip that persona so unrelated tests can still run.
+//
+// Usage:
+//   dezycro-resolve-auth [<path>]            # defaults to .dezycro/auth.local.json
+//   eval "$(dezycro-resolve-auth)"; ./verifier run ...
+//
+// Output is newline-separated `export KEY='value'` statements, where single
+// quotes inside the value are POSIX-escaped. MUST be consumed via `eval`
+// (or `source /dev/stdin <<< "$(...)"`), NOT via `env $(…)` — the latter
+// skips shell quote-stripping and hands the binary a value that still starts
+// with a literal `'`, producing `invalid character '\'' looking for …` parse
+// errors from the Go JSON decoder.
+
+const fs = require("fs");
+const os = require("os");
+const { execSync } = require("child_process");
+
+function shQuote(s) {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+function resolveSecret(raw) {
+  if (typeof raw !== "string") return raw;
+  if (raw.startsWith("!file:")) {
+    const p = raw.slice(6).replace(/^~(?=\/|$)/, os.homedir());
+    return fs.readFileSync(p, "utf8").replace(/\s+$/, "");
+  }
+  if (raw.startsWith("!env:")) {
+    const name = raw.slice(5);
+    if (!(name in process.env)) throw new Error(`env var not set: ${name}`);
+    return process.env[name];
+  }
+  if (raw.startsWith("!cmd:")) {
+    const cmd = raw.slice(5);
+    const out = execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    const trimmed = out.replace(/\s+$/, "");
+    if (!trimmed) throw new Error(`empty stdout from: ${cmd}`);
+    return trimmed;
+  }
+  return raw;
+}
+
+function substitute(obj, secrets) {
+  if (typeof obj === "string") {
+    return obj.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name) => {
+      if (!(name in secrets)) throw new Error(`\${${name}} not in secrets`);
+      return secrets[name];
+    });
+  }
+  if (Array.isArray(obj)) return obj.map((x) => substitute(x, secrets));
+  if (obj && typeof obj === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = substitute(v, secrets);
+    return out;
+  }
+  return obj;
+}
+
+function main() {
+  const authPath = process.argv[2] || ".dezycro/auth.local.json";
+  if (!fs.existsSync(authPath)) {
+    process.stderr.write(`[dezycro-resolve-auth] no auth file at ${authPath}; emitting nothing\n`);
+    return;
+  }
+  let doc;
+  try {
+    doc = JSON.parse(fs.readFileSync(authPath, "utf8"));
+  } catch (e) {
+    process.stderr.write(`[dezycro-resolve-auth] parse error in ${authPath}: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  const secrets = {};
+  for (const [k, v] of Object.entries(doc.secrets || {})) {
+    try {
+      secrets[k] = resolveSecret(v);
+    } catch (e) {
+      process.stderr.write(`[dezycro-resolve-auth] warning: secret ${k}: ${e.message}\n`);
+    }
+  }
+
+  const lines = [];
+  for (const [name, p] of Object.entries(doc.personas || {})) {
+    if (!p || !p.envVar) continue;
+    try {
+      const cfg = substitute(p.config || {}, secrets);
+      lines.push(`export ${p.envVar}=${shQuote(JSON.stringify(cfg))}`);
+    } catch (e) {
+      process.stderr.write(`[dezycro-resolve-auth] warning: persona '${name}' skipped: ${e.message}\n`);
+    }
+  }
+
+  if (lines.length) process.stdout.write(lines.join("\n") + "\n");
+}
+
+main();