gentyr 1.3.0

package/docs/SETUP-GUIDE.md

@@ -0,0 +1,419 @@
+# GENTYR Setup Guide
+
+<!-- CREDENTIAL-PHASE-MAP
+GITHUB_TOKEN: Phase 2: GitHub Token
+GITHUB_PAT: Phase 2: GitHub Token
+RENDER_API_KEY: Phase 3: Render API Key
+VERCEL_TOKEN: Phase 4: Vercel Token
+CLOUDFLARE_API_TOKEN: Phase 5: Cloudflare API Token
+CLOUDFLARE_ZONE_ID: Phase 5: Cloudflare API Token
+SUPABASE_SERVICE_ROLE_KEY: Phase 6: Supabase Credentials
+SUPABASE_URL: Phase 6: Supabase Credentials
+SUPABASE_ANON_KEY: Phase 6: Supabase Credentials
+SUPABASE_ACCESS_TOKEN: Phase 6: Supabase Credentials
+ELASTIC_API_KEY: Phase 7: Elastic Cloud Credentials
+ELASTIC_CLOUD_ID: Phase 7: Elastic Cloud Credentials
+RESEND_API_KEY: Phase 8: Resend API Key
+CODECOV_TOKEN: Phase 9: Codecov Token
+OP_CONNECT_TOKEN: Phase 1: 1Password Service Account
+-->
+
+This guide walks through setting up credentials for each service in the GENTYR stack.
+
+## Prerequisites
+
+- Node.js 20+
+- pnpm 8+
+- 1Password CLI (`op`) installed: `brew install --cask 1password-cli`
+- Claude Code installed
+
+## Browser Automation Notes
+
+These instructions are frequently consumed by AI agents using browser automation (e.g., Claude Cowork). The tips below each phase help agents avoid common pitfalls.
+
+**General patterns for all phases:**
+- Prefer `form_input` over `click` + `type` for filling form fields — it's more reliable and handles special characters (e.g., `/`, `@`) that `type` may misinterpret as keyboard shortcuts.
+- Use `read_page(filter="interactive")` to discover form elements and buttons before interacting with them.
+- Use `zoom` tool to verify small UI elements (checkboxes, toggles, dropdown states) before and after interaction.
+- Use `get_page_text` to extract values from the page (API keys, tokens, IDs) rather than trying to select/copy text via UI interactions.
+- **Chrome Extension interference**: Browser extensions (especially 1Password) can inject errors like `Cannot access a chrome-extension:// URL` across unrelated sites. Recovery: call `navigate()` to the current URL to refresh the page, then retry. If errors persist on a specific page, try navigating away and back.
+- When a page action triggers a new tab or popup, use `get_browser_state()` to check for the new tab, then `switch_tab()` to it.
+
+## Phase 1: 1Password Service Account
+
+1. Open 1Password Desktop app
+2. Go to **Settings > Integrations > Service Accounts**
+3. Click **Create Service Account**
+4. Name it "Claude Code MCP"
+5. Grant access to: Production, Staging, Preview vaults
+6. Copy the service account token
+7. The setup command will inject this into your MCP config
+
+**Shell profile sync**: When you run `npx gentyr init --op-token <TOKEN>`, the installer writes a managed block to `~/.zshrc` (or `~/.bashrc`) so that subprocesses spawned from your shell inherit the token automatically:
+
+```
+# BEGIN GENTYR OP
+# 1Password Service Account Token (managed by GENTYR — do not edit manually)
+export OP_SERVICE_ACCOUNT_TOKEN="<token>"
+# END GENTYR OP
+```
+
+This block is updated on reinstall and removed on uninstall. `.mcp.json` is always the source of truth. If they ever drift, `credential-health-check.js` warns at session start and `setup-validate.js` reports a `shellSync` failure.
+
+## Phase 2: GitHub Token
+
+1. Go to https://github.com/settings/tokens
+2. Click **Generate new token (fine-grained)**
+3. Name: "GENTYR - {project-name}"
+4. Repository access: Select your repository
+5. Permissions (all required for GENTYR MCP tools):
+   - **Actions**: Read and Write (workflow runs, re-runs, cancellation)
+   - **Contents**: Read and Write (file read/write via GitHub API)
+   - **Issues**: Read and Write (issue creation, comments)
+   - **Pull requests**: Read and Write (PR creation, merge, file listing)
+   - **Secrets**: Read and Write (repository and environment secrets)
+   - **Environments**: Read and Write (deployment environment management)
+6. Copy the token
+
+**Validation:** setup-validate probes each permission endpoint. Missing permissions appear as warnings with direct links to fix.
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **GitHub**
+- Item type: Login
+- Fields:
+  - `token` = [paste the token]
+- Predefined path: `op://Production/GitHub/token`
+
+> **Browser automation tip — GitHub:** Use `form_input` (not `type`) for the token name field, especially if the name contains `/` or other special characters that browsers interpret as shortcuts.
+
+> **Browser automation tip — 1Password (applies to all phases):** When adding fields to a 1Password item, the `+ add another field` button and its dropdown chevron (`▼`) are **separate clickable controls**. Click the chevron first to select the field type (e.g., "password"), then click the `+` button to create the field. After creating the field, use `form_input` to set both the label and value. Verify the save completed by checking for a URL change or confirmation indicator — 1Password auto-saves on navigation but not always on field edit. Built-in template fields (e.g., "username", "password" on Login items) have pre-set names that may not match the required field name — always add a **new custom field** with the exact name specified (e.g., `token`, `api-key`).
+
+## Phase 3: Render API Key
+
+1. Go to https://dashboard.render.com/account/api-keys
+2. Click **Create API Key**
+3. Name: "GENTYR - {project-name}"
+4. Copy the API key
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Render**
+- Item type: Login
+- Fields:
+  - `api-key` = [paste the API key]
+- Predefined path: `op://Production/Render/api-key`
+
+> **Browser automation tip — Render:** The API key is displayed once after creation. Use `get_page_text` immediately to capture it before navigating away.
+
+## Phase 4: Vercel Token
+
+1. Go to https://vercel.com/account/tokens
+2. Click **Create Token**
+3. Name: "GENTYR - {project-name}"
+4. Scope: **Full Account** (required for deployments, projects, env vars, domains)
+5. Copy the token
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Vercel**
+- Item type: Login
+- Fields:
+  - `token` = [paste the token]
+- Predefined path: `op://Production/Vercel/token`
+
+To find your Team ID:
+1. Go to https://vercel.com/teams
+2. Click your team
+3. Go to **Settings > General**
+4. Copy the Team ID
+
+> **Browser automation tip — Vercel:** The token is displayed once after creation. Use `get_page_text` to capture it. The Team ID on the Settings page can also be extracted via `get_page_text` — look for the string labeled "Team ID".
+
+## Phase 5: Cloudflare API Token
+
+1. Go to https://dash.cloudflare.com/profile/api-tokens
+2. Click **Create Token**
+3. Use template: **Edit zone DNS** (required for DNS record management)
+4. Zone Resources: Include > Specific zone > your domain
+5. Copy the token
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Cloudflare**
+- Item type: Login
+- Fields:
+  - `api-token` = [paste the API token]
+- Predefined path: `op://Production/Cloudflare/api-token`
+
+To find your Zone ID:
+1. Go to your domain's overview page in Cloudflare
+2. The Zone ID is in the right sidebar under **API**
+
+**Non-secret (share in chat during /setup-gentyr):**
+- Cloudflare Zone ID (32-character hex string)
+  - Find at: Cloudflare Dashboard > your domain > right sidebar under "API"
+
+> **Browser automation tip — Cloudflare:** The Zone ID is visible on the domain overview page without clicking into any sub-menus. Use `get_page_text` to extract it — look for a 32-character hex string near "Zone ID" in the right sidebar. The token creation flow uses a multi-step wizard with dropdowns for zone selection; use `read_page(filter="interactive")` to find the correct selectors at each step.
+
+## Phase 6: Supabase Credentials
+
+### Service Role Key (secret)
+1. Go to your Supabase project dashboard
+2. Navigate to **Project Settings > API**
+3. Copy the **service_role** key (secret — never expose in frontend)
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Supabase**
+- Item type: Login
+- Fields:
+  - `service-role-key` = [paste service role key]
+- Predefined path: `op://Production/Supabase/service-role-key`
+
+### Non-secret identifiers (share in chat during /setup-gentyr)
+- **Supabase URL** (e.g., `https://abcdefghijklmnop.supabase.co`)
+  - Find at: Supabase Dashboard > Project Settings > API > URL
+- **Supabase Anon Key** (public API key, embedded in frontend code)
+  - Find at: Supabase Dashboard > Project Settings > API > anon (public)
+
+### Management Access Token
+1. Go to https://supabase.com/dashboard/account/tokens
+2. Click **Generate new token**
+3. Name: "GENTYR - {project-name}"
+4. Copy the token
+
+**1Password Storage:**
+- Vault: **Production**
+- Item: **Supabase** (same item as service-role-key)
+- Fields:
+  - `access-token` = [paste management token]
+- Predefined path: `op://Production/Supabase/access-token`
+
+**What this enables:** `supabase_sql`, `supabase_push_migration`, `supabase_list_migrations`, `supabase_get_project` MCP tools. Without it, `supabase_list_tables` and `supabase_describe_table` use a PostgREST fallback with slightly less detail.
+
+> **Browser automation tip — Supabase:** The API page shows the `anon` key, `service_role` key, and URL all on one page. Use `get_page_text` to extract all three at once. The `service_role` key is hidden behind a "Reveal" button — click it first, then extract. For the management access token at `supabase.com/dashboard/account/tokens`, the token is displayed once after generation — capture immediately with `get_page_text`.
+
+## Phase 7: Elastic Cloud Credentials
+
+### API Keys
+
+#### For Hosted Deployments
+1. Go to https://cloud.elastic.co
+2. Open your deployment
+3. Click **Manage** > **Security** > **Create API Key**
+4. Create two keys:
+   - "Ingest" key (for backend logging): Index privileges on `logs-*`
+   - "Query" key (for Claude Code): Read privileges on `logs-*`
+
+#### For Serverless Projects
+1. Go to https://cloud.elastic.co/serverless
+2. Open your project
+3. Go to **Project Settings** > **Management** > **API Keys**
+4. Create two keys:
+   - "Ingest" key (for backend logging): Index privileges on `logs-*`
+   - "Query" key (for Claude Code): Read privileges on `logs-*`
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Elastic**
+- Item type: Login
+- Fields:
+  - `api-key` = [paste ingest API key]
+  - `api-key-query` = [paste query API key]
+- Predefined paths:
+  - `op://Production/Elastic/api-key` (ingest — for backend logging, not used by GENTYR)
+  - `op://Production/Elastic/api-key-query` (query — **used by GENTYR MCP `elastic-logs` server**)
+
+### Connection Identifier
+
+Provide **one** of the following (not both):
+
+**Non-secret (share in chat during /setup-gentyr):**
+
+**Option A — Hosted Deployment (Cloud ID):**
+- Elastic Cloud ID (e.g., `my-deployment:dXMtY2VudH...`)
+  - Find at: Elastic Cloud > Deployments > your deployment > Cloud ID
+  - Stored as: `ELASTIC_CLOUD_ID` in vault-mappings.json
+
+**Option B — Serverless Project (Endpoint URL):**
+- Elasticsearch endpoint URL (e.g., `https://my-project-abc123.es.us-central1.gcp.elastic.cloud`)
+  - Find at: Elastic Cloud > Serverless > your project > Endpoints
+  - Stored as: `ELASTIC_ENDPOINT` in vault-mappings.json
+
+> **Browser automation tip — Elastic Cloud:** The "Create API Key" UI has toggles and role selectors that are unreliable with browser automation. **Strongly prefer using the Dev Tools Console** (REST API) instead:
+>
+> 1. Navigate to your project's Dev Tools Console: `https://cloud.elastic.co/.../app/dev_tools#/console/shell`
+> 2. Run the following REST command to create each key:
+>    ```
+>    POST /_security/api_key
+>    {
+>      "name": "log-query-readonly",
+>      "role_descriptors": {
+>        "logs_reader": {
+>          "indices": [{ "names": ["logs-*"], "privileges": ["read"] }]
+>        }
+>      }
+>    }
+>    ```
+> 3. Use `get_page_text` to extract the JSON response from the console output panel.
+> 4. The response contains `id`, `api_key`, and `encoded` fields. **Store the `encoded` value** — this is the base64-encoded `id:api_key` string ready for use. A valid encoded key is ~60 characters. If it's ~36 characters or less, the key was likely truncated during copy.
+> 5. For the ingest key, change `"privileges": ["read"]` to `"privileges": ["index", "create_index"]`.
+>
+> The Endpoint URL for Serverless projects can be found at the project's Endpoints page — use `get_page_text` to extract it.
+
+## Phase 8: Resend API Key
+
+1. Go to https://resend.com/api-keys
+2. Click **Create API Key**
+3. Name: "GENTYR - {project-name}"
+4. Permission: **Full access** (recommended)
+   - "Full access" enables domain management, API key listing, and all MCP tools
+   - "Sending access" is sufficient if you only need email sending (setup-validate will warn about limited tools)
+5. Domain: your domain (or leave blank for all domains)
+6. Copy the API key
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Resend**
+- Item type: Login
+- Fields:
+  - `api-key` = [paste the API key]
+- Predefined path: `op://Production/Resend/api-key`
+
+> **Browser automation tip — Resend:** The API key is displayed once after creation. Use `get_page_text` to capture it immediately. The permission dropdown ("Full access" vs "Sending access") should be selected before clicking "Create".
+
+## Phase 9: Codecov Token
+
+1. Go to https://app.codecov.io
+2. Navigate to your repository settings
+3. Copy the **Upload Token**
+
+**1Password Storage:**
+- Vault: **Production**
+- Item title: **Codecov**
+- Item type: Login
+- Fields:
+  - `token` = [paste the upload token]
+- Predefined path: `op://Production/Codecov/token`
+
+> **Browser automation tip — Codecov:** Codecov uses GitHub OAuth for login, which can be disrupted by Chrome extensions. If the OAuth redirect fails or loops, ask the user to log in manually in the browser first, then navigate directly to the repository settings page. The Upload Token is visible on the settings page without any reveal/toggle interaction — use `get_page_text` to extract it.
+
+## How Credentials Work
+
+After creating each credential in your service provider, store it in 1Password:
+
+1. Open 1Password Desktop app
+2. Navigate to the **Production** vault
+3. Create a new item with the exact title and field names specified in each phase above
+4. Run `/setup-gentyr` — it verifies these exist and writes `op://` references to `.claude/vault-mappings.json`
+5. The MCP launcher resolves these at server startup — credentials exist only in process memory
+
+**Non-secret identifiers** (URLs, zone IDs, cloud IDs) don't need 1Password. Share them in chat during `/setup-gentyr` and they'll be written directly to `vault-mappings.json`.
+
+## Phase 10: Branch Protection & Deployment Pipeline
+
+GENTYR enforces a strict merge chain: `feature/* -> preview -> staging -> main (production)`.
+
+### Why the Merge Chain Matters
+
+- **Feature branches** can only merge into `preview` (no approval needed)
+- **Preview** can only merge into `staging` (deputy-CTO approval)
+- **Staging** can only merge into `main` (CTO approval)
+- Direct merges from feature branches to staging/main are **forbidden**
+
+### CI Enforcement
+
+GitHub has no native rule to restrict which source branch a PR comes from. GENTYR includes a `merge-chain-check.yml` CI workflow that enforces this. It must be added as a **required status check** on all protected branches.
+
+The workflow template is at: `node_modules/gentyr/templates/config/merge-chain-check.yml.template`
+
+Copy it to `.github/workflows/merge-chain-check.yml` in your project.
+
+### Branch Protection (GitHub Teams)
+
+Go to: Repository > Settings > Branches > Add branch protection rule
+
+**For each branch (`preview`, `staging`, `main`):**
+1. Require a pull request before merging
+2. Require status checks to pass (include `Validate Merge Chain`)
+3. Block force pushes
+4. Do not allow bypassing settings
+
+**Additional for `staging`:** Require 1 approving review (deputy-CTO)
+**Additional for `main`:** Require 1 approving review (CTO) + Security Scan check
+
+See `node_modules/gentyr/docs/DEPLOYMENT-FLOW.md` for complete branch protection instructions.
+
+### GitHub Enterprise Cloud
+
+If on Enterprise Cloud, also configure:
+- Organization Rulesets for cross-repo enforcement
+- Deployment Protection Rules for staging/production environments
+- Merge Queue for the `main` branch
+
+### `gh` CLI Authentication
+
+The automated promotion pipelines use `gh` CLI for PR operations. Ensure it's authenticated:
+
+```bash
+gh auth login
+gh auth status
+```
+
+### Automated Promotion
+
+Once branch protection is configured, GENTYR's hourly automation handles promotion:
+
+- **Preview -> Staging**: Every 6 hours, reviews new commits and promotes if stable (24h or bug-fix)
+- **Staging -> Main**: Nightly at midnight, promotes if staging is 24h+ stable (requires CTO approval)
+
+### Health Monitoring
+
+GENTYR monitors deployed environments:
+
+- **Staging**: Every 3 hours -- checks Render, Vercel, Elasticsearch, Codecov
+- **Production**: Every 1 hour -- same checks + CTO escalation for issues
+
+Enable/disable via `.claude/autonomous-mode.json`:
+```json
+{
+  "previewPromotionEnabled": true,
+  "stagingPromotionEnabled": true,
+  "stagingHealthMonitorEnabled": true,
+  "productionHealthMonitorEnabled": true
+}
+```
+
+## Permission Validation
+
+After completing setup, run permission validation to verify all credentials work and have correct permissions:
+
+```bash
+node node_modules/gentyr/scripts/setup-validate.js
+```
+
+This makes **read-only** API calls to each service and reports:
+
+| Status | Meaning |
+|--------|---------|
+| **pass** | Credential works with correct permissions |
+| **warn** | Credential works but with limited permissions (some MCP tools may not function) |
+| **fail** | Credential is invalid, expired, or lacks required permissions |
+| **skip** | Credential not configured |
+
+Each failure includes specific **remediation instructions** with URLs to fix the issue.
+
+### Required API Permissions by Service
+
+| Service | Required Permissions | Key Type |
+|---------|---------------------|----------|
+| **Vercel** | Full Account scope | Personal token |
+| **Render** | Full API access | API key (not scoped) |
+| **GitHub** | Actions R/W, Contents R/W, Issues R/W, PRs R/W, Secrets R/W, Environments R/W | Fine-grained PAT |
+| **Cloudflare** | Zone DNS Edit (for specific zone) | API token (Edit zone DNS template) |
+| **Supabase** | Service role key (admin), anon key (public) | Project API keys |
+| **Resend** | Full access (recommended) or Sending access (limited) | API key |
+| **Elastic** | Read-only on `logs-*` indices | API key |
+| **Codecov** | Any valid token (read-only API) | Upload token |
+| **1Password** | Service account with vault access | Service account token |

package/docs/STACK.md

@@ -0,0 +1,109 @@
+# the stack
+
+GENTYR chose managed services so every agent, hook, and server is purpose-built for exactly these tools. No abstraction layers. No configuration matrices. No "bring your own database."
+
+Every technology below exists for one reason: it removes a decision that agents would otherwise need a human to make. Supabase provides auth, storage, and a database behind a single API. Vercel deploys frontend on push. Render deploys backend on push. 1Password resolves secrets without exposing values. The stack is not configurable because configurability is the enemy of autonomous operation.
+
+Thirty MCP servers connect agents to these services. Each server speaks one protocol to one provider. When an agent needs to deploy, it talks to the Render server. When it needs a secret, it talks to the 1Password server. When it needs to query logs, it talks to the Elastic server. No adapters. No middleware. No indirection.
+
+This is the stack. Learn it or choose a different framework.
+
+---
+
+## Application Layer
+
+**TypeScript (strict, ESM)** is the only language. Strict mode catches type errors before agents write tests. ESM modules mean consistent import semantics across frontend, backend, and tooling. Every package in the monorepo shares the same language, the same compiler, the same rules.
+
+**Next.js on Vercel** handles the frontend. Vercel's zero-config deployment means agents push code and it goes live. No Dockerfile, no build pipeline to maintain, no CDN to configure. The MCP server (`vercel`) manages deployments, environment variables, and project settings through Vercel's API.
+
+**Hono on Render** runs the backend API. Hono is lightweight, TypeScript-native, and fast. Render provides persistent web services with health checks, auto-deploy from git, and managed TLS. The MCP server (`render`) handles service management, deploy triggers, and environment configuration.
+
+**Supabase** provides PostgreSQL, authentication, file storage, and row-level security through a single dashboard and API. Agents interact through the MCP server (`supabase`) for schema management and through the Supabase client SDK for runtime queries. RLS policies are enforced at the database level, which means security doesn't depend on application code.
+
+**Zod** handles runtime validation. Every API endpoint, every webhook handler, every configuration file gets a Zod schema. The compliance checker verifies this. Silent JSON parsing without validation is a spec violation.
+
+## Infrastructure Layer
+
+**pnpm monorepo** organizes the project. A single `pnpm-workspace.yaml` defines the package graph. Shared types live in `packages/shared`. The logger lives in `packages/logger`. Build and test commands run from the root.
+
+**GitHub + Actions** handles source control and CI/CD. The merge chain (`feature -> preview -> staging -> main`) is enforced locally by hooks and remotely by branch protection rules. Actions run tests, lint, and type-checking on every push.
+
+**1Password** is the single source of truth for secrets. Every credential is an `op://` reference. The MCP server (`onepassword`) resolves references at runtime. The secret-sync server pushes secrets to deployment platforms. Nothing is stored on disk. Nothing passes through agent context.
+
+**Cloudflare** manages DNS. The MCP server (`cloudflare`) handles record creation and verification. Free tier is sufficient for most projects.
+
+**Elastic Cloud** provides centralized logging. Application logs ship in ECS format from the structured logger (`packages/logger`). The MCP server (`elastic-logs`) queries Elasticsearch for error patterns, warning trends, and service health. The CTO dashboard aggregates log metrics from this source.
+
+**Resend** handles transactional email. The MCP server (`resend`) sends emails and checks delivery status. Simple API, reliable delivery, no SMTP configuration.
+
+**Codecov** reports test coverage. The MCP server (`codecov`) fetches coverage data for the CTO dashboard. Coverage trends are tracked over time and displayed in the testing section.
+
+## Testing Layer
+
+**Vitest** runs unit and integration tests. Fast, TypeScript-native, compatible with the monorepo structure. Test failures trigger automatic agent spawns via the test-failure-reporter hook.
+
+**Playwright** runs end-to-end and browser tests. The MCP server (`playwright`) and feedback MCP servers (`playwright-feedback`, `programmatic-feedback`) enable AI personas to test the product as real users. No headless browser configuration needed.
+
+---
+
+## MCP Server Mappings
+
+Each infrastructure service maps to one or more MCP servers that give agents programmatic access:
+
+| Service | MCP Server(s) | Capabilities |
+|---------|--------------|--------------|
+| 1Password | `onepassword`, `secret-sync` | Resolve `op://` refs, sync to platforms, run with injected secrets |
+| Render | `render` | Service management, deploys, environment variables, logs |
+| Vercel | `vercel` | Project management, deploys, environment variables |
+| Supabase | `supabase` | Schema management, migrations, RLS policies |
+| GitHub | `github` | PRs, issues, Actions, branch management |
+| Cloudflare | `cloudflare` | DNS records, zone management |
+| Elastic Cloud | `elastic-logs` | Log queries, error analysis, volume metrics |
+| Resend | `resend` | Email sending, delivery status |
+| Codecov | `codecov` | Coverage data, trends |
+| Chrome | `chrome-bridge` | Browser automation, page interaction, debugging |
+
+Internal MCP servers (not tied to external providers):
+
+| Server | Purpose |
+|--------|---------|
+| `todo-db` | Task database (SQLite) |
+| `deputy-cto` | Triage pipeline, commit review, CTO questions |
+| `agent-tracker` | Agent lifecycle, spawn/reap tracking |
+| `agent-reports` | Report submission and query |
+| `cto-reports`, `cto-report` | Dashboard data aggregation |
+| `review-queue` | Commit review queue |
+| `session-events` | Session lifecycle events |
+| `feedback-reporter`, `feedback-explorer`, `user-feedback` | Feedback pipeline |
+| `playwright-feedback`, `programmatic-feedback` | AI persona testing |
+| `specs-browser` | Specification document access |
+| `setup-helper` | Installation and configuration |
+| `makerkit-docs` | MakerKit documentation reference |
+| `shared` | Shared utilities across servers |
+
+---
+
+## Monorepo Structure
+
+```
+project-root/
+├── node_modules/gentyr/        # GENTYR (npm package)
+├── .claude/config/services.json # Project-specific service IDs
+├── products/
+│   └── {product-name}/
+│       └── apps/
+│           ├── backend/        # Hono on Render
+│           ├── web/            # Next.js on Vercel (MakerKit)
+│           └── extension/      # Browser extension (optional)
+├── packages/
+│   ├── shared/                 # Shared types and utilities
+│   └── logger/                 # Structured logger (ECS format)
+├── integrations/               # Platform connectors
+├── specs/
+│   ├── global/                 # System-wide invariants
+│   ├── local/                  # Component specifications
+│   └── reference/              # Development guides
+├── render.yaml                 # Render blueprint
+├── pnpm-workspace.yaml         # Monorepo config
+└── .github/workflows/ci.yml    # CI pipeline
+```