@iamu-dev/iamu 0.2.0-beta.2 → 0.2.0-beta.4

package/dist/bin.js

@@ -11896,7 +11896,7 @@ var init_credentials = __esm({
     "use strict";
     init_dist2();
     init_dist();
-    DEFAULT_API_URL = "https://api.iamu.dev";
+    DEFAULT_API_URL = "https://app.iamu.dev";
     CredentialsFileError = class extends IamuConfigError {
       /**
        * @param path - The unreadable credentials file.
@@ -11993,7 +11993,7 @@ async function resolveCloudProject(opts) {
     commandError("Not cloud-linked. Run `iamu auth login` to connect.", opts);
     return null;
   }
-  const apiUrl = ctx.config.cloud_api_url ?? "https://api.iamu.dev";
+  const apiUrl = ctx.config.cloud_api_url ?? DEFAULT_API_URL;
   try {
     assertSecureApiUrl(apiUrl, "cloud_api_url");
   } catch (err) {
@@ -13502,12 +13502,24 @@ async function browserLogin(apiUrl, opts, t) {
       chalk8.red(`
   Auth session expired or failed (HTTP ${result.status}).`)
     );
+    console.error(
+      chalk8.dim("  Re-run `iamu auth login` to start a new login session.\n")
+    );
     process.exitCode = 1;
     return null;
   }
   if (result.kind === "timeout") {
     s.stop("Authentication timed out.");
-    console.error(chalk8.red("\n  Authentication timed out. Try again."));
+    console.error(
+      chalk8.red(
+        "\n  Authentication timed out (no approval received within 2 minutes)."
+      )
+    );
+    console.error(
+      chalk8.dim(
+        "  \u2022 Complete browser authorization faster, or authenticate non-interactively with --token <key>.\n  \u2022 Local setup is unaffected \u2014 re-run `iamu auth login` anytime.\n"
+      )
+    );
     process.exitCode = 1;
     return null;
   }
@@ -13533,7 +13545,12 @@ async function startAuthSession(apiUrl, timeoutMs) {
     if (!res.ok) {
       console.error(
         chalk8.red(
-          `  Failed to start auth session: ${res.text || `HTTP ${res.status}`}`
+          `  Failed to start auth session at ${apiUrl}: ${res.text || `HTTP ${res.status}`}`
+        )
+      );
+      console.error(
+        chalk8.dim(
+          "  \u2022 The cloud service may be experiencing downtime or maintenance.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
         )
       );
       process.exitCode = 1;
@@ -13547,7 +13564,13 @@ async function startAuthSession(apiUrl, timeoutMs) {
     return { sessionId: data.sessionId, loginUrl: data.loginUrl };
   } catch (err) {
     console.error(
-      chalk8.red("  Cannot reach Iamu Cloud.") + chalk8.dim(` (${errorMessage(err)})`)
+      chalk8.red(`  Cannot reach Iamu Cloud (${apiUrl}).`) + chalk8.dim(`
+  Reason: ${errorMessage(err)}`)
+    );
+    console.error(
+      chalk8.dim(
+        "\n  \u2022 Check your internet connection or proxy settings.\n  \u2022 If using a custom instance, pass --url <api-url> or set IAMU_API_URL.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
+      )
     );
     process.exitCode = 1;
     return null;
@@ -18393,7 +18416,8 @@ function defaultFrontmatter(type2, id, slug, name, opts) {
         ...base,
         name,
         role: opts.role ?? "TODO",
-        ...opts.disposition ? { disposition: opts.disposition } : {}
+        ...opts.disposition ? { disposition: opts.disposition } : {},
+        ...opts.access ? { access: opts.access } : {}
       };
     case "outline":
       return { ...base, title: name, ...description };
@@ -18462,7 +18486,7 @@ async function newEntity(type2, opts) {
   }
   const id = randomUUID9();
   const frontmatter = defaultFrontmatter(entityType, id, slug, opts.name, opts);
-  const body = "";
+  const body = opts.body ?? opts.narrative ?? "";
   try {
     const record = await writeEntity(
       projectRoot,
@@ -20464,7 +20488,7 @@ function registerCloudCommands(program2) {
     "Connect to local cloud stack (default port: 3000)"
   ).addOption(
     new Option("-s, --staging", "Connect to staging cloud stack").hideHelp()
-  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://api.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
+  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://app.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
     "--project <project-id>",
     "Cloud project ID to link to, or `new` to create one. Required in a non-interactive shell when cloud projects exist"
   ).option("--no-browser", "Do not launch browser automatically").addHelpText(
@@ -20620,6 +20644,9 @@ function registerProjectCommands(program2) {
   program2.command("new <type>").helpGroup("Project:").description(
     "Create a new entity (persona, outline, capability, source, scenario)"
   ).requiredOption("--name <name>", "Entity name").option("--slug <slug>", "Custom entity slug (defaults to slugified name)").option("--role <role>", "Role description (persona only)").option("--disposition <text>", "Disposition / attitude (persona only)").option(
+    "--access <role>",
+    "Access role or testing account key (persona only)"
+  ).option("--body <text>", "Markdown body / narrative content").option("--narrative <text>", "Alias for --body").option(
     "--description <text>",
     "One-line description (capability, outline)"
   ).option("--outline <slug>", "Outline slug (scenario only)").option("--persona <slug>", "Persona slug (scenario only)").option(

package/dist/index.js

@@ -11968,7 +11968,7 @@ var init_credentials = __esm({
     "use strict";
     init_dist2();
     init_dist();
-    DEFAULT_API_URL = "https://api.iamu.dev";
+    DEFAULT_API_URL = "https://app.iamu.dev";
     CredentialsFileError = class extends IamuConfigError {
       /**
        * @param path - The unreadable credentials file.
@@ -12118,7 +12118,7 @@ async function resolveCloudProject(opts) {
     commandError("Not cloud-linked. Run `iamu auth login` to connect.", opts);
     return null;
   }
-  const apiUrl = ctx.config.cloud_api_url ?? "https://api.iamu.dev";
+  const apiUrl = ctx.config.cloud_api_url ?? DEFAULT_API_URL;
   try {
     assertSecureApiUrl(apiUrl, "cloud_api_url");
   } catch (err) {
@@ -13481,12 +13481,24 @@ async function browserLogin(apiUrl, opts, t) {
       chalk8.red(`
   Auth session expired or failed (HTTP ${result.status}).`)
     );
+    console.error(
+      chalk8.dim("  Re-run `iamu auth login` to start a new login session.\n")
+    );
     process.exitCode = 1;
     return null;
   }
   if (result.kind === "timeout") {
     s.stop("Authentication timed out.");
-    console.error(chalk8.red("\n  Authentication timed out. Try again."));
+    console.error(
+      chalk8.red(
+        "\n  Authentication timed out (no approval received within 2 minutes)."
+      )
+    );
+    console.error(
+      chalk8.dim(
+        "  \u2022 Complete browser authorization faster, or authenticate non-interactively with --token <key>.\n  \u2022 Local setup is unaffected \u2014 re-run `iamu auth login` anytime.\n"
+      )
+    );
     process.exitCode = 1;
     return null;
   }
@@ -13512,7 +13524,12 @@ async function startAuthSession(apiUrl, timeoutMs) {
     if (!res.ok) {
       console.error(
         chalk8.red(
-          `  Failed to start auth session: ${res.text || `HTTP ${res.status}`}`
+          `  Failed to start auth session at ${apiUrl}: ${res.text || `HTTP ${res.status}`}`
+        )
+      );
+      console.error(
+        chalk8.dim(
+          "  \u2022 The cloud service may be experiencing downtime or maintenance.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
         )
       );
       process.exitCode = 1;
@@ -13526,7 +13543,13 @@ async function startAuthSession(apiUrl, timeoutMs) {
     return { sessionId: data.sessionId, loginUrl: data.loginUrl };
   } catch (err) {
     console.error(
-      chalk8.red("  Cannot reach Iamu Cloud.") + chalk8.dim(` (${errorMessage(err)})`)
+      chalk8.red(`  Cannot reach Iamu Cloud (${apiUrl}).`) + chalk8.dim(`
+  Reason: ${errorMessage(err)}`)
+    );
+    console.error(
+      chalk8.dim(
+        "\n  \u2022 Check your internet connection or proxy settings.\n  \u2022 If using a custom instance, pass --url <api-url> or set IAMU_API_URL.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
+      )
     );
     process.exitCode = 1;
     return null;
@@ -18372,7 +18395,8 @@ function defaultFrontmatter(type2, id, slug, name, opts) {
         ...base,
         name,
         role: opts.role ?? "TODO",
-        ...opts.disposition ? { disposition: opts.disposition } : {}
+        ...opts.disposition ? { disposition: opts.disposition } : {},
+        ...opts.access ? { access: opts.access } : {}
       };
     case "outline":
       return { ...base, title: name, ...description };
@@ -18441,7 +18465,7 @@ async function newEntity(type2, opts) {
   }
   const id = randomUUID9();
   const frontmatter = defaultFrontmatter(entityType, id, slug, opts.name, opts);
-  const body = "";
+  const body = opts.body ?? opts.narrative ?? "";
   try {
     const record = await writeEntity(
       projectRoot,
@@ -20435,7 +20459,7 @@ function registerCloudCommands(program) {
     "Connect to local cloud stack (default port: 3000)"
   ).addOption(
     new Option("-s, --staging", "Connect to staging cloud stack").hideHelp()
-  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://api.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
+  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://app.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
     "--project <project-id>",
     "Cloud project ID to link to, or `new` to create one. Required in a non-interactive shell when cloud projects exist"
   ).option("--no-browser", "Do not launch browser automatically").addHelpText(
@@ -20591,6 +20615,9 @@ function registerProjectCommands(program) {
   program.command("new <type>").helpGroup("Project:").description(
     "Create a new entity (persona, outline, capability, source, scenario)"
   ).requiredOption("--name <name>", "Entity name").option("--slug <slug>", "Custom entity slug (defaults to slugified name)").option("--role <role>", "Role description (persona only)").option("--disposition <text>", "Disposition / attitude (persona only)").option(
+    "--access <role>",
+    "Access role or testing account key (persona only)"
+  ).option("--body <text>", "Markdown body / narrative content").option("--narrative <text>", "Alias for --body").option(
     "--description <text>",
     "One-line description (capability, outline)"
   ).option("--outline <slug>", "Outline slug (scenario only)").option("--persona <slug>", "Persona slug (scenario only)").option(

package/dist/templates/skills/iamu-setup.md

@@ -44,33 +44,48 @@ Explore the codebase automatically — do NOT ask the user what files to read. B
 
 Extract these key dimensions:
 
-1. **Domain** — what does this product do, in one phrase (mandatory).
-2. **Jurisdiction** — country / region (optional — only include if evident from codebase/locale/terms or if legal frameworks apply).
-3. **Regulations (`governed_by`)** — specific compliance frameworks (AFS 2023:2, GDPR, HIPAA, ISO 27001, etc.). **Strictly optional:** only extract if the repo explicitly references legal or compliance standards. Most software is not in a regulated domain; do NOT invent or guess regulations for standard SaaS/apps.
-4. **Primary Personas** — determine the 1–2 most important user archetypes that stress-test this product (e.g. End User / Consumer vs. Admin / Operator, or First-Timer vs. Power User). Propose:
+1. **Domain & Purpose** — what this product does, core workflows, and problem space (mandatory).
+2. **Jurisdiction & Regulations (`governed_by`)** — country/region and specific compliance frameworks (AFS 2023:2, GDPR, HIPAA, ISO 27001, etc.). **Strictly optional:** only extract if the repo explicitly references legal or compliance standards. Do NOT invent regulations for standard apps.
+3. **Key Actors & Roles** — the main user archetypes and roles discovered in the codebase (auth models, routes, permissions).
+4. **Dev Access & Auth** — how personas switch or log in during local dev/test (e.g. dev persona switcher, seeded accounts, storage key, mock headers). Essential for walkthrough automation.
+5. **Key Terminology (`glossary`)** — 2–4 domain-specific terms or acronyms found in the codebase.
+6. **Primary Personas** — determine the 1–2 most critical user archetypes that stress-test this product (e.g. End User / Frontline vs. Admin / Compliance, or First-Timer vs. Power User). Propose:
    - Name and Role
    - Disposition / perspective (patience level, tech literacy, primary friction triggers)
 
-Also collect silently (write to `context.yml` but do NOT present for confirmation):
-- **Actors** — all identified roles and their responsibilities.
-- **Glossary** — domain-specific terms (helps persona language fidelity).
-- **Access** — if the project documents how to switch user or role in a dev or test environment (a persona switcher, seeded accounts, a storage key), record that mechanism as `access`. It is what lets a walkthrough run as the persona instead of as whoever happens to be signed in. Never record passwords or tokens — name where they live.
-
-Do NOT collect architecture (agent reads the codebase directly — tech stack doesn't affect walkthroughs).
+Do NOT collect code architecture (agent reads the codebase directly — tech stack doesn't affect walkthroughs).
 
 **If there is no code (greenfield, design phase):** ask the user: what does this project do, who are the users, what domain, and are there any specific regulations?
 
-**Present a short proposal for confirmation:**
+**Present the proposal with clean, structured Markdown for confirmation:**
 
-```
-Your project: <domain> (<jurisdiction if known>)
-[Regulations: <reg1>, <reg2>]  <-- omit line entirely if none
+```markdown
+### 📋 Discovered Project Context
+
+- **Domain & Purpose:** <Concise description of the product and problem space>
+- **Jurisdiction & Rules:** <Country/region and compliance frameworks, or "None identified">
+- **Key Roles Identified:** <List of detected roles and their responsibilities>
+- **Dev Access & Auth:** <Detected mechanism to switch/assume personas in dev, or "Standard login">
+- **Domain Terminology:** <2–4 key terms/acronyms found in the codebase, if any>
+
+---
+
+### 🎭 Proposed Primary Personas
 
-Proposed primary personas:
-  1. <Name> (<Role>) — <Key disposition & perspective>
-  2. <Name> (<Role>) — <Key disposition & perspective>
+#### 1. <Name> — *<Role / Title>*
+- **Context & Usage:** <Where and how they use the app (e.g., mobile on the floor vs. desktop in office)>
+- **Disposition:** <Patience level, technical confidence, key motivations>
+- **Friction Triggers:** <Specific interactions that cause friction, drop-off, or failure>
 
-Confirm context & scaffold these personas? (yes / edit / suggest-others / skip-personas)
+#### 2. <Name> — *<Role / Title>*
+- **Context & Usage:** <Where and how they use the app>
+- **Disposition:** <Patience level, technical confidence, key motivations>
+- **Friction Triggers:** <Specific interactions that cause friction, drop-off, or failure>
+
+---
+
+**Next step:**
+Reply **"yes"** to save this context to `iamu/context.yml` and scaffold these personas, or tell me what to adjust (e.g., change roles, edit domain, or add/skip personas).
 ```
 
 Wait for the user to confirm or correct before writing. The user only needs to verify domain and choose whether to accept, edit, suggest alternative personas, or defer persona creation.
@@ -122,16 +137,17 @@ Persist the step-2 summary as structured fields so every scenario draft and walk
 
 4. **Scaffold confirmed personas (unless `skip-personas` selected):**
 
-   Always use the CLI to scaffold valid persona entities with schema-compliant UUIDs, slugs, and timestamps:
+   Use the CLI to scaffold valid persona entities with schema-compliant UUIDs, slugs, frontmatter, and narrative body in a single command:
    ```bash
-   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
+   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>" [--access "<account-or-role>"] --json
    ```
 
-   Then open the created file (`iamu/personas/<slug>.md`) and write 2–4 sentences of background narrative into the markdown body below the frontmatter, detailing their technical habits, patience level, and specific friction triggers.
+   If `iamu/context.yml` specifies an `access` mechanism, pass `--access "<role>"` matching an existing product account/role.
 
-   If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field in frontmatter to match an existing product account/role.
-
-   Run `iamu validate --all`.
+   Once all confirmed personas are created, run validation once:
+   ```bash
+   iamu validate --all
+   ```
 
 5. Confirm: "Context saved and personas seeded in iamu/personas/. Run `iamu-new` to draft your first scenario." (or "Context saved. Run `iamu-new` to draft your first scenario." if personas were skipped).
 
@@ -157,11 +173,15 @@ Three outcomes:
 
 **Linking:**
 
-1. Run `iamu auth login` (add `--url <api-url>` only if the user names a self-hosted cloud). It opens the sign-in page in the user's browser and waits up to two minutes — tell the user to approve it there. Allow the command at least 150 seconds before your shell tool times out. If your shell cannot wait that long, or runs where no browser can open (remote or container session), ask the user to run `iamu auth login` in their own terminal and tell you when it is done.
-2. **Never pick the cloud project for the user.** In a non-interactive shell with existing cloud projects, login stops after sign-in and lists them as `iamu auth login --project <id>` lines plus `--project new`. Show that list, ask which project this repository belongs to, then re-run with their choice — the stored sign-in is reused, no second browser trip. Linking pushes every local persona, scenario and finding into the chosen project; a wrong guess leaks them into someone else's.
-3. On success the output ends with `Dashboard: <url>` and, when an agent host was detected, `iamu-sync MCP server registered`. Relay both in two lines: the dashboard link, and that restarting the agent session loads the team tools (work requests, teammate-change alerts).
+1. Tell the user: "Opening browser for Iamu Cloud login..." then run `iamu auth login`. Allow the command at least 150 seconds for the user to complete sign-in in their browser. If your shell cannot wait that long, or runs where no browser can open (remote or container session), ask the user to run `iamu auth login` in their own terminal and tell you when it is done.
+2. **Never pick the cloud project for the user.** In a non-interactive shell with existing cloud projects, login stops after sign-in and lists them as `iamu auth login --project <id>` lines plus `--project new`. Show that list, ask which project this repository belongs to, then re-run with their choice — the stored sign-in is reused, no second browser trip.
+3. On success the output ends with `Dashboard: <url>` and, when an agent host was detected, `iamu-sync MCP server registered`. Relay both: the dashboard link, and that restarting the agent session loads the team tools (work requests, teammate-change alerts).
 
-If login fails (cloud unreachable, sign-in timed out), report the error in one line and continue — setup is complete without the cloud.
+If login times out or fails (cloud unreachable, sign-in timed out, or network error):
+- Explain clearly what happened: "Cloud linking could not be completed (<echo specific reason from command output>)."
+- Reassure the user: "Your local project setup is 100% complete and fully functional. Personas, scenarios, outlines, and walkthroughs run locally without cloud."
+- Provide the next step for linking: "You can link to Iamu Cloud anytime later by running `iamu auth login` in your terminal."
+- Point to the next creative action: "Next: run `iamu-new` to draft your first scenario."
 
 All three outcomes leave a usable local setup. Cloud is strictly additive.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.4",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,8 +58,8 @@
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu/tsconfig": "0.1.0",
-    "@iamu-dev/protocol": "0.1.0"
+    "@iamu-dev/protocol": "0.1.0",
+    "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",