@rubytech/create-maxy 1.0.477 → 1.0.478

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.477",
+  "version": "1.0.478",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/neo4j/schema.cypher

@@ -561,3 +561,26 @@ FOR (ag:AccessGrant) ON (ag.magicToken);
 // Status filtering — admin listing of active/expired/revoked grants.
 CREATE INDEX access_grant_status IF NOT EXISTS
 FOR (ag:AccessGrant) ON (ag.status);
+
+// ----------------------------------------------------------
+// AdminUser node — device-level admin identity
+// Platform-native. Represents a human who administers one or
+// more accounts via the admin agent. Exists at the device level
+// (not account-scoped). Linked to accounts via ADMIN_OF.
+//
+// Properties:
+//   userId     — UUID, matches entry in platform/config/users.json
+//   name       — display name (e.g. "Adam")
+//   createdAt  — ISO 8601 timestamp
+//
+// Relationships:
+//   (AdminUser)-[:ADMIN_OF {role, grantedAt}]->(LocalBusiness)
+//   role: "owner" | "admin" — label only, no enforcement
+//   grantedAt: ISO 8601 timestamp
+//
+// No vector index — AdminUser is always queried deterministically
+// by userId. Semantic search over admin users is not a use case.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT admin_user_id_unique IF NOT EXISTS
+FOR (au:AdminUser) REQUIRE au.userId IS UNIQUE;

package/payload/platform/plugins/anthropic/PLUGIN.md

@@ -5,7 +5,7 @@ description: Guide users through obtaining an Anthropic API key to power the pub
 
 # Anthropic / Claude Setup
 
-The public agent runs on the Anthropic API. This plugin handles obtaining, storing, and verifying an API key from console.anthropic.com.
+The public agent runs on the Anthropic API. This plugin handles obtaining, storing, and verifying an API key from the Anthropic Console (platform.claude.com).
 
 ## When to activate
 
@@ -24,12 +24,13 @@ The public agent runs on the Anthropic API. This plugin handles obtaining, stori
 
 | Task | When to use | Skill |
 |------|-------------|-------|
-| Obtain API key via browser | `api-key-verify` returns `missing` or user wants to rotate key | `skills/get-api-key/SKILL.md` |
+| Obtain API key | `api-key-verify` returns `missing` or user wants to rotate key | `skills/get-api-key/SKILL.md` |
 
 ## References
 
 | Topic | When to use | Reference |
 |-------|-------------|-----------|
 | Troubleshooting & FAQ | API key rejected, billing questions, manual key entry | `references/setup-guide.md` |
+| Console API surface | Understanding the endpoints used by the get-api-key skill | `references/console-api.md` |
 
 For API key acquisition (including during onboarding), use the `skills/get-api-key/SKILL.md` skill. For troubleshooting and common questions, load the reference.

package/payload/platform/plugins/anthropic/references/console-api.md

@@ -0,0 +1,186 @@
+# Anthropic Console — Internal API Reference
+
+Captured 2026-04-07 from `platform.claude.com` (formerly `console.anthropic.com`).
+
+These are undocumented internal endpoints used by the Console's React frontend. They are not part of Anthropic's public API and may change without notice.
+
+## Authentication
+
+Cookie-based via `sessionKey` cookie:
+- Domain: `.platform.claude.com`
+- Flags: `httpOnly`, `secure`, `SameSite=Lax`
+- Expiry: 7 days from sign-in
+
+The cookie is set during the OAuth sign-in flow (Google or email verification). Because it is `httpOnly`, it cannot be read by JavaScript — but `fetch()` with `credentials: 'include'` sends it automatically.
+
+Common request headers (set by the Console frontend, not required for API auth):
+- `content-type: application/json`
+- `anthropic-client-platform: web_console`
+
+## Org Discovery
+
+The Console is org-scoped. All billing and key management endpoints require an org UUID. A user may have multiple orgs (e.g., a consumer chat org and an API org).
+
+### GET /api/organizations
+
+Returns all orgs the user belongs to.
+
+```json
+[
+  {
+    "id": 55730262,
+    "uuid": "1882f41b-...",
+    "name": "Neo's Individual Org",
+    "billing_type": "prepaid",
+    "capabilities": ["api", "api_individual"],
+    "created_at": "2025-06-28T06:40:26.071676Z"
+  }
+]
+```
+
+**Selecting the API org:** Filter for the org whose `capabilities` array contains `"api"`. Consumer orgs have `capabilities: ["claude_max", "chat"]` and no API key management.
+
+### GET /api/bootstrap
+
+Returns current user account info and org memberships. Useful for getting the user's name and email.
+
+```json
+{
+  "account": {
+    "tagged_id": "user_01YW5...",
+    "uuid": "ff1a722d-...",
+    "email_address": "user@example.com",
+    "full_name": "Neo Aeon",
+    "memberships": [
+      { "organization": { "uuid": "...", "name": "..." }, "role": "admin" }
+    ]
+  }
+}
+```
+
+## Billing Endpoints
+
+All GET, org-scoped. Replace `{orgId}` with the org UUID.
+
+### GET /api/organizations/{orgId}/prepaid/credits
+
+Credit balance.
+
+```json
+{
+  "amount": 504,
+  "currency": "USD",
+  "auto_reload_settings": {
+    "enabled": true,
+    "threshold_in_minor_units": 500,
+    "reload_to_in_minor_units": 1500
+  },
+  "pending_invoice_amount_cents": null
+}
+```
+
+`amount` is in **cents** (minor currency units). 504 = $5.04.
+
+### GET /api/organizations/{orgId}/current_spend
+
+Current billing period spend.
+
+```json
+{
+  "amount": 39,
+  "resets_at": "2026-05-01T00:00:00Z"
+}
+```
+
+`amount` is in **cents**. 39 = $0.39.
+
+### GET /api/organizations/{orgId}/prepaid/auto_recharge
+
+Auto-recharge configuration.
+
+```json
+{
+  "status": "active",
+  "stripe_error_code": null,
+  "target_amount": 1500,
+  "threshold_amount": 500
+}
+```
+
+Amounts in **cents**.
+
+### GET /api/organizations/{orgId}/payment_method
+
+Payment method on file.
+
+```json
+{
+  "brand": null,
+  "country": null,
+  "last4": null,
+  "type": "link"
+}
+```
+
+## API Key Endpoints
+
+### GET /api/console/organizations/{orgId}/api_keys
+
+List all API keys for the org.
+
+```json
+[
+  {
+    "id": "apikey_01XY5wjo397BKKLjHNgvHATx",
+    "type": "api_key",
+    "name": "maxy",
+    "workspace_id": null,
+    "created_at": "2026-03-22T19:08:25.868735Z",
+    "created_by": { "id": "user_01YW5...", "type": "user" },
+    "partial_key_hint": "sk-ant-api03-kNh...HAAA",
+    "status": "active",
+    "expires_at": null
+  }
+]
+```
+
+`status` values: `"active"`, `"inactive"` (disabled), `"archived"` (deleted).
+
+### POST /api/console/organizations/{orgId}/workspaces/default/api_keys
+
+Create a new API key. The `raw_key` is only returned once at creation time.
+
+**Request:**
+```json
+{ "name": "Maxy" }
+```
+
+**Response (200):**
+```json
+{
+  "id": "apikey_01Hkz...",
+  "type": "api_key",
+  "name": "Maxy",
+  "workspace_id": null,
+  "created_at": "2026-04-07T11:05:39.949811Z",
+  "created_by": { "id": "user_01YW5...", "type": "user" },
+  "partial_key_hint": "sk-ant-api03-cPs...1AAA",
+  "status": "active",
+  "expires_at": null,
+  "raw_key": "sk-ant-api03-cPsiih...ewev1AAA"
+}
+```
+
+### POST /api/console/organizations/{orgId}/workspaces/default/api_keys/{keyId}
+
+Update key status.
+
+**Disable:**
+```json
+{ "status": "inactive" }
+```
+
+**Archive (delete):**
+```json
+{ "status": "archived" }
+```

package/payload/platform/plugins/anthropic/references/setup-guide.md

@@ -18,10 +18,10 @@ If the automated browser flow is unavailable or the user already has a key:
 
 | Problem | Solution |
 |---------|----------|
-| API key rejected | Verify it starts with `sk-ant-`. Check that billing is set up on console.anthropic.com — keys don't work without an active billing method. |
+| API key rejected | Verify it starts with `sk-ant-`. Check that billing is set up on platform.claude.com — keys don't work without an active billing method. |
 | Key created on zero-balance account | Keys created before credits are loaded are permanently rejected. Create a new key after adding credits. |
 | "Which provider should I pick?" | Anthropic / Claude is the right choice. It powers all of the public agent's conversations and reasoning. |
-| Browser automation failed | Tell the user to get a key from console.anthropic.com/settings/keys in their own browser, then paste it in the chat. |
+| Browser automation failed | Tell the user to get a key from platform.claude.com/settings/keys in their own browser, then paste it in the chat. |
 
 ---
 
@@ -32,4 +32,4 @@ If the automated browser flow is unavailable or the user already has a key:
 | "How much does the API cost?" | Anthropic charges per API call. For small business use, typical costs are a few dollars per month. See anthropic.com/pricing for current rates. |
 | "Do I need to restart after adding a key?" | No — the API key is applied immediately. |
 | "Can I rotate my key?" | Yes — run the `get-api-key` skill again or paste a new key. The old key is overwritten. |
-| "What if my key stops working?" | Check that billing is still active on console.anthropic.com. If the account ran out of credits, add more and the existing key should resume working (unless it was created on a zero-balance account). |
+| "What if my key stops working?" | Check that billing is still active on platform.claude.com. If the account ran out of credits, add more and the existing key should resume working (unless it was created on a zero-balance account). |

package/payload/platform/plugins/anthropic/skills/get-api-key/SKILL.md

@@ -1,51 +1,115 @@
 ---
 name: get-api-key
-description: Obtain an Anthropic API key by delegating browser automation to the browser-specialist subagent. Verifies credits are loaded before creating a key to prevent permanently rejected keys.
+description: Obtain an Anthropic API key by calling the Console's internal API endpoints via browser_evaluate, falling back to screenshot-based browser automation if direct API calls fail.
 ---
 
 # Get Anthropic API Key
 
-Obtain an API key from console.anthropic.com on behalf of the user. Browser automation is delegated to `specialists:browser-specialist` — a plugin-defined specialist subagent. All Playwright interaction runs in the specialist's isolated context, keeping the main session lightweight. The user can see the browser via the VNC viewer displayed in the chat.
+Obtain an API key from the Anthropic Console (platform.claude.com) on behalf of the user. The browser-specialist calls Console API endpoints directly via `browser_evaluate` + `fetch()` — the browser's session cookies handle auth automatically. This is orders of magnitude faster than navigating pages and interpreting screenshots.
 
 **Critical ordering rule:** Credits must be confirmed on the account before creating an API key. Keys created on a zero-balance account are permanently rejected by the Anthropic API — even after credits are added later.
 
+**Auth model:** The Console uses an `httpOnly` session cookie (`sessionKey`) set during sign-in. Because it's `httpOnly`, JavaScript can't read it — but `fetch()` with `credentials: 'include'` sends it automatically. All API calls in the briefs below rely on this.
+
 ## Steps
 
 1. **Show the browser.** Call `render-component` with:
    - `name: "browser-viewer"`
    - `data: { title: "Anthropic Console" }`
 
-2. **Dispatch browser-specialist for billing assessment.** Use the Agent tool with `specialists:browser-specialist` as the subagent type. Brief:
-
-   > Navigate to https://console.anthropic.com/settings/billing. Take a screenshot to assess the page. Report what you see: Is there a credit balance shown? Does it say "Buy credits to get started"? Is a sign-in page shown instead? Report the billing status and any dollar amount visible. If sign-in is required, report "SIGN_IN_REQUIRED" and stop.
+2. **Dispatch browser-specialist for sign-in check and billing assessment.** Use the Agent tool with `specialists:browser-specialist` as the subagent type. Brief:
+
+   > Navigate to https://platform.claude.com/settings/billing. Wait for the page to load.
+   >
+   > Then use `browser_evaluate` to run this JavaScript:
+   > ```js
+   > (async () => {
+   >   try {
+   >     const orgsRes = await fetch('/api/organizations', { credentials: 'include', headers: { 'content-type': 'application/json' } });
+   >     if (orgsRes.status === 401 || orgsRes.status === 403) return { status: 'SIGN_IN_REQUIRED' };
+   >     const orgs = await orgsRes.json();
+   >     const apiOrg = orgs.find(o => o.capabilities && o.capabilities.includes('api'));
+   >     if (!apiOrg) return { status: 'NO_API_ORG', orgs: orgs.map(o => ({ name: o.name, capabilities: o.capabilities })) };
+   >     const creditsRes = await fetch(`/api/organizations/${apiOrg.uuid}/prepaid/credits`, { credentials: 'include', headers: { 'content-type': 'application/json' } });
+   >     if (!creditsRes.ok) return { status: 'BILLING_CHECK_FAILED', httpStatus: creditsRes.status };
+   >     const credits = await creditsRes.json();
+   >     return { status: 'OK', orgId: apiOrg.uuid, orgName: apiOrg.name, creditsCents: credits.amount, currency: credits.currency };
+   >   } catch (e) { return { status: 'FETCH_ERROR', error: e.message }; }
+   > })()
+   > ```
+   >
+   > Report the result object exactly as returned. Do not interpret or summarize — pass the JSON back verbatim.
 
 3. **Handle the billing result.**
-   - If the specialist reports a credit balance greater than $0: proceed to step 6 (create key).
-   - If the specialist reports "SIGN_IN_REQUIRED": proceed to step 4.
-   - If the specialist reports no credits, zero balance, or "Buy credits to get started": proceed to step 5.
-   - If the specialist reports any other error (CAPTCHA, navigation failure, tool unavailable) or the billing status cannot be determined: warn the user that billing status could not be confirmed, and proceed to step 6 (create key). Do not block onboarding on an inconclusive check.
+   - `status: "OK"` with `creditsCents > 0`: Credits available. Note the `orgId` — it's needed for key creation. Proceed to step 6.
+   - `status: "OK"` with `creditsCents === 0`: No credits. Proceed to step 5.
+   - `status: "SIGN_IN_REQUIRED"`: Proceed to step 4.
+   - `status: "NO_API_ORG"`: Tell the user: "Your Anthropic account doesn't have an API organization. Visit platform.claude.com and set up API access, then try again."
+   - `status: "BILLING_CHECK_FAILED"` or `status: "FETCH_ERROR"`: The direct API call failed. Fall back to the screenshot-based billing check (step 2F).
 
 4. **Sign-in required.** Tell the user: "Sign in to your Anthropic account in the browser. You can use Google sign-in or enter your email — Anthropic will send a verification email. Open the email in the same browser (open a new tab) to complete sign-in. If you don't have an account, create one — you will need to add credits before a key can be created." Wait for the user to confirm they have signed in. Then return to step 2 to re-check billing.
 
-5. **No credits — guide the user.** Tell the user: "Your Anthropic account needs credits loaded before I can create an API key. Add credits or enable auto-top-up on the billing page. Let me know when you're done." Wait for confirmation, then dispatch browser-specialist to re-check the billing page (same brief as step 2). If credits are now present, proceed to step 6. If still no credits, repeat this step (maximum 3 attempts). After 3 attempts with no credits detected, tell the user: "Credits still not detected. You can add them at console.anthropic.com/settings/billing and then ask me to create the API key again."
-
-6. **Dispatch browser-specialist for key creation.** Use the Agent tool with `specialists:browser-specialist` as the subagent type. Brief:
-
-   > Navigate to https://console.anthropic.com/settings/keys. Take a screenshot to verify you are on the API Keys page. Create a new API key named "Maxy": find and click the "Create Key" button, fill the key name with "Maxy", submit the form. After creation, look for a string starting with sk-ant- on the page — Anthropic shows the key only once. If found, call api-key-store with the key. Report what happened. If sign-in is required, report "SIGN_IN_REQUIRED" and stop.
+5. **No credits — guide the user.** Tell the user: "Your Anthropic account needs credits loaded before I can create an API key. Add credits or enable auto-top-up on the billing page. Let me know when you're done." Wait for confirmation, then re-dispatch the billing check (step 2). If credits are now present, proceed to step 6. If still no credits, repeat this step (maximum 3 attempts). After 3 attempts with no credits detected, tell the user: "Credits still not detected. You can add them at platform.claude.com/settings/billing and then ask me to create the API key again."
+
+6. **Dispatch browser-specialist for key creation.** Use the Agent tool with `specialists:browser-specialist` as the subagent type. Include the `orgId` from step 3. Brief:
+
+   > Use `browser_evaluate` to run this JavaScript (replace ORG_ID with the orgId from the billing check):
+   > ```js
+   > (async () => {
+   >   try {
+   >     const res = await fetch('/api/console/organizations/ORG_ID/workspaces/default/api_keys', {
+   >       method: 'POST',
+   >       credentials: 'include',
+   >       headers: { 'content-type': 'application/json' },
+   >       body: JSON.stringify({ name: 'Maxy' })
+   >     });
+   >     if (res.status === 401 || res.status === 403) return { status: 'SIGN_IN_REQUIRED' };
+   >     if (!res.ok) return { status: 'CREATE_FAILED', httpStatus: res.status, body: await res.text() };
+   >     const key = await res.json();
+   >     if (!key.raw_key) return { status: 'NO_RAW_KEY', keyId: key.id };
+   >     return { status: 'KEY_CREATED', rawKey: key.raw_key, keyName: key.name, keyId: key.id };
+   >   } catch (e) { return { status: 'FETCH_ERROR', error: e.message }; }
+   > })()
+   > ```
+   >
+   > If the result has `status: "KEY_CREATED"`, call `api-key-store` with the `rawKey` value. Report the full result object back.
+   >
+   > If the result has any other status, report it back verbatim — do not attempt to navigate the Console UI.
 
 7. **Handle the key creation result.**
-   - If the specialist reports the key was stored: proceed to step 9 (verify).
-   - If the specialist reports "SIGN_IN_REQUIRED": this is unexpected since sign-in was handled during the billing check. Tell the user to sign in, wait for confirmation, then retry step 6 once. If it fails again, proceed to step 8 (fallback).
-   - If the specialist reports any other error (CAPTCHA, key not extractable, navigation failure): proceed to step 8 (fallback).
+   - `status: "KEY_CREATED"` and specialist confirms key was stored: proceed to step 9 (verify).
+   - `status: "SIGN_IN_REQUIRED"`: this is unexpected since sign-in was handled during the billing check. Tell the user to sign in, wait for confirmation, then retry step 6 once. If it fails again, proceed to step 8 (fallback).
+   - `status: "CREATE_FAILED"` or `status: "FETCH_ERROR"`: The direct API call failed. Fall back to the screenshot-based key creation (step 6F).
+   - `status: "NO_RAW_KEY"`: The key was created but the response didn't include the full key value. Proceed to step 8 (manual fallback).
 
 8. **Fallback.** Tell the user: "I could not extract the key automatically. Please copy it from the browser and paste it here in the chat." When the user pastes a key starting with `sk-ant-`, call `api-key-store` with it. Then proceed to step 9.
 
 9. **Verify the key works.** Call the `api-key-verify` MCP tool. Handle each status:
    - `valid`: Confirm to the user — "API key stored and verified. Your public agent is ready."
    - `billing`: Credits were confirmed before key creation, so this is unexpected. Tell the user: "The key was stored but credits may not have propagated yet. Please wait a moment." Retry `api-key-verify` once after a brief pause. If still `billing`, tell the user: "Credits are not being detected yet. The key is stored — the public agent will start working once Anthropic recognises the credits on your account."
-   - `auth_error`: The key was rejected. Tell the user: "The stored key was rejected by Anthropic. It may have been copied incorrectly. Let's try again." Return to step 6 (maximum 2 retries — if it fails 3 times total, tell the user to visit console.anthropic.com/settings/keys in their own browser and paste the key manually).
+   - `auth_error`: The key was rejected. Tell the user: "The stored key was rejected by Anthropic. It may have been copied incorrectly. Let's try again." Return to step 6 (maximum 2 retries — if it fails 3 times total, tell the user to visit platform.claude.com/settings/keys in their own browser and paste the key manually).
    - `error`: Could not verify (network or Anthropic issue). Tell the user: "I couldn't verify the key right now — this is likely a temporary issue. The key is stored and should work once the connection is restored."
 
+## Fallback Steps (screenshot-based)
+
+These steps are used when `browser_evaluate` + `fetch()` fails. They replicate the original browser automation approach.
+
+### Step 2F: Screenshot-based billing check
+
+Dispatch browser-specialist with brief:
+
+> Navigate to https://platform.claude.com/settings/billing. Take a screenshot to assess the page. Report what you see: Is there a credit balance shown? Does it say "Buy credits to get started"? Is a sign-in page shown instead? Report the billing status and any dollar amount visible. If sign-in is required, report "SIGN_IN_REQUIRED" and stop.
+
+Handle the result the same as step 3, mapping the specialist's text observations to the structured statuses.
+
+### Step 6F: Screenshot-based key creation
+
+Dispatch browser-specialist with brief:
+
+> Navigate to https://platform.claude.com/settings/keys. Take a screenshot to verify you are on the API Keys page. Create a new API key named "Maxy": find and click the "Create Key" button, fill the key name with "Maxy", submit the form. After creation, look for a string starting with sk-ant- on the page — Anthropic shows the key only once. If found, call api-key-store with the key. Report what happened. If sign-in is required, report "SIGN_IN_REQUIRED" and stop.
+
+Handle the result the same as step 7.
+
 ## Important
 
 - **`render-component` is required before any browser-specialist dispatch.** The browser-viewer component is what makes the VNC browser visible to the user. Without it, automation runs invisibly. Always call `render-component` with `name: "browser-viewer"` and confirm it renders before dispatching a browser-specialist subagent.
@@ -53,5 +117,10 @@ Obtain an API key from console.anthropic.com on behalf of the user. Browser auto
 - The browser is visible to the user via VNC. They can see everything the specialist does.
 - The user must sign in themselves — the specialist does not fill credentials.
 - For email verification: tell the user to open the verification email in a new tab in the same VNC browser (not on their own device). This keeps the sign-in session in the same browser context.
-- Anthropic shows the API key only once after creation. If the user navigates away before it is captured, they must create a new key.
-- If the browser-specialist is not available (not installed, Agent tool fails), skip the browser-viewer component entirely and tell the user to get a key from console.anthropic.com in their own browser, then paste it in the chat.
+- Anthropic shows the API key only once after creation. With the direct API approach, the `raw_key` is in the JSON response — but if the specialist fails to call `api-key-store` before its context ends, the key is lost and a new one must be created.
+- If the browser-specialist is not available (not installed, Agent tool fails), skip the browser-viewer component entirely and tell the user to get a key from platform.claude.com in their own browser, then paste it in the chat.
+- The Console URL `console.anthropic.com` redirects to `platform.claude.com`. All briefs use `platform.claude.com` to avoid redirect latency.
+
+## API Reference
+
+For the complete captured API surface (endpoint details, response schemas, auth mechanism), see `references/console-api.md`.

package/payload/platform/scripts/seed-neo4j.sh

@@ -222,6 +222,75 @@ fi
 
 echo "  Account $ACCOUNT_ID at $ACCOUNT_DIR"
 
+# ------------------------------------------------------------------
+# 1b. Create first admin user (migration from .admin-pin)
+# ------------------------------------------------------------------
+
+CONFIG_DIR="$PROJECT_DIR/config"
+USERS_FILE="$CONFIG_DIR/users.json"
+
+# Resolve the brand-specific config directory for .admin-pin location.
+# Mirrors the logic in platform/ui/app/lib/paths.ts.
+_CONFIG_DIR_NAME=".maxy"
+if [ -f "$CONFIG_DIR/brand.json" ]; then
+  _BRAND_CFG_DIR=$(python3 -c "import json; print(json.load(open('$CONFIG_DIR/brand.json')).get('configDir',''))" 2>/dev/null || true)
+  [ -n "$_BRAND_CFG_DIR" ] && _CONFIG_DIR_NAME="$_BRAND_CFG_DIR"
+fi
+ADMIN_PIN_FILE="$HOME/$_CONFIG_DIR_NAME/.admin-pin"
+
+# Only create users.json if it doesn't exist AND .admin-pin exists (migration case).
+# Fresh installs: no .admin-pin yet (set during onboarding). The session route falls
+# back to .admin-pin when users.json is absent — no migration needed until next seed.
+if [ ! -f "$USERS_FILE" ] && [ -f "$ADMIN_PIN_FILE" ]; then
+  USER_ID="$(cat /proc/sys/kernel/random/uuid 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')"
+  PIN_HASH="$(cat "$ADMIN_PIN_FILE")"
+
+  # Create users.json with the first user entry.
+  # PINs are stored as SHA-256 hashes — same format as .admin-pin.
+  cat > "$USERS_FILE" << USERS_EOF
+[{"userId":"$USER_ID","name":"Owner","pin":"$PIN_HASH"}]
+USERS_EOF
+  echo "  [seed] created initial user: userId=$USER_ID"
+
+  # Add the user to account.json's admins array.
+  # The template includes "admins": [] — populate it with the owner entry.
+  if [ -f "$ACCOUNT_DIR/account.json" ]; then
+    python3 -c "
+import json, sys
+with open('$ACCOUNT_DIR/account.json', 'r') as f:
+    config = json.load(f)
+config.setdefault('admins', [])
+if not any(a.get('userId') == '$USER_ID' for a in config['admins']):
+    config['admins'].append({'userId': '$USER_ID', 'role': 'owner'})
+with open('$ACCOUNT_DIR/account.json', 'w') as f:
+    json.dump(config, f, indent=2)
+    f.write('\n')
+"
+    echo "  Added userId=$USER_ID as owner to account.json admins"
+  fi
+elif [ -f "$USERS_FILE" ]; then
+  # Re-run: users.json exists. Read the first user's ID for Neo4j seeding.
+  USER_ID=$(python3 -c "import json; print(json.load(open('$USERS_FILE'))[0]['userId'])" 2>/dev/null || true)
+  [ -n "$USER_ID" ] && echo "  Existing users.json found, userId=$USER_ID"
+
+  # Backfill admins in account.json if missing (existing accounts pre-Task 248).
+  if [ -f "$ACCOUNT_DIR/account.json" ] && ! grep -q '"admins"' "$ACCOUNT_DIR/account.json"; then
+    python3 -c "
+import json
+with open('$ACCOUNT_DIR/account.json', 'r') as f:
+    config = json.load(f)
+config['admins'] = [{'userId': '$USER_ID', 'role': 'owner'}]
+with open('$ACCOUNT_DIR/account.json', 'w') as f:
+    json.dump(config, f, indent=2)
+    f.write('\n')
+"
+    echo "  Backfilled admins array in account.json"
+  fi
+else
+  echo "  No .admin-pin found — skipping users.json creation (fresh install)"
+  USER_ID=""
+fi
+
 # ------------------------------------------------------------------
 # 2. Apply Neo4j schema (constraints + indexes only)
 # ------------------------------------------------------------------
@@ -236,4 +305,27 @@ echo "==> Applying schema (constraints, indexes, vector indexes)..."
 "$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" \
     -f "$NEO4J_DIR/schema.cypher"
 
+# ------------------------------------------------------------------
+# 3. Create AdminUser node + ADMIN_OF relationship
+# ------------------------------------------------------------------
+
+if [ -n "${USER_ID:-}" ]; then
+  # Escape single quotes for Cypher string interpolation (e.g. O'Brien → O''Brien).
+  USER_NAME=$(python3 -c "import json; n=json.load(open('$USERS_FILE'))[0]['name']; print(n.replace(\"'\",\"''\"))" 2>/dev/null || echo "Owner")
+  CREATED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  echo "==> Creating AdminUser node for userId=$USER_ID"
+  "$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" << CYPHER_EOF
+MERGE (au:AdminUser {userId: '$USER_ID'})
+ON CREATE SET au.name = '$USER_NAME', au.createdAt = '$CREATED_AT'
+ON MATCH SET au.name = '$USER_NAME'
+WITH au
+MATCH (b:LocalBusiness {accountId: '$ACCOUNT_ID'})
+MERGE (au)-[r:ADMIN_OF]->(b)
+ON CREATE SET r.role = 'owner', r.grantedAt = '$CREATED_AT'
+RETURN au.userId, b.accountId;
+CYPHER_EOF
+  echo "  AdminUser node created/updated"
+fi
+
 echo "  Done."

package/payload/platform/templates/account.json

@@ -9,5 +9,6 @@
   "contextMode": "claude-code",
   "enabledPlugins": [],
   "purchasedPlugins": [],
-  "defaultAgent": ""
+  "defaultAgent": "",
+  "admins": []
 }