@elevasis/sdk 1.5.5 → 1.7.0

package/reference/claude-config/skills/project/SKILL.md

@@ -35,6 +35,58 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 - `/project checklist <client> "<milestone>"` — View checklist for a milestone.
 - `/project delete <client>` — Delete project (cascades milestones, tasks, notes).
 
+## Prerequisites
+
+**Run from the project root** (the directory containing `.elevasis`). Before issuing any other commands, run:
+
+```bash
+pnpm elevasis-sdk doctor
+```
+
+If `doctor` fails, **stop immediately and surface the error** — do not retry other commands. Fix the reported issue first (missing `.env`, bad API key, wrong directory, etc.), then re-run `doctor` before proceeding.
+
+---
+
+## Invocation Contract
+
+All `elevasis-sdk` commands in this skill use the wrapper script form:
+
+```bash
+pnpm elevasis-sdk <subcommand> [flags]
+```
+
+This form is available from the **project root** — the directory that contains the `.elevasis` marker file. The `.elevasis` file is the project-root anchor: `elevasis-sdk` walks up from its invocation directory until it finds this file, then resolves `.env` and all relative paths from that location. After the project-root refactor, CWD within the project tree matters less — but you must still be somewhere inside the project directory tree.
+
+The long form `pnpm -C operations exec elevasis-sdk <subcommand>` still works and is equivalent. Use the short wrapper form (`pnpm elevasis-sdk`) in all new automation and agent scripts.
+
+**If the `.elevasis` marker is missing**, the CLI exits with:
+
+```
+Not inside an Elevasis project. Run this command from a project directory (an Elevasis project has a .elevasis file at its root).
+```
+
+If you see this error, confirm you are inside a project that was created from the template and has the `.elevasis` marker at its root.
+
+---
+
+## Transient Input Files (`tmp/`)
+
+Agents that need to pass structured JSON to `request:submit` or `exec` should write the file to `<projectRoot>/tmp/` rather than to an arbitrary path. The `tmp/` directory is tracked in git (via `tmp/.gitkeep`) but its contents are gitignored, so transient files never pollute the commit history.
+
+**Workflow:**
+
+1. Write the input payload to `tmp/<descriptive-name>.json` from the project root.
+2. Pass the path to the CLI command using the relative form — it resolves against the project root automatically:
+
+   ```bash
+   pnpm elevasis-sdk request:submit -f tmp/request-report.json --cleanup-input
+   pnpm elevasis-sdk exec my-workflow -f tmp/exec-payload.json --cleanup-input
+   ```
+
+3. The `--cleanup-input` flag deletes the file automatically after a successful command. On failure the file is left intact for inspection.
+
+**Safety guard:** `--cleanup-input` only deletes files that are under `<projectRoot>/tmp/`. If the resolved path is outside `tmp/`, the CLI prints a warning to stderr and leaves the file untouched. Files passed via `--input <json>` (inline JSON, no file) are never affected.
+
 ---
 
 ## Orientation Mode (bare `/project` invocation)
@@ -43,10 +95,11 @@ When invoked without a subcommand, enter **project mode**: present the portfolio
 
 ### Flow
 
-1. **List active work** — run:
+1. **List active work** — `--status` accepts exactly one value. Run two calls and merge the results:
 
    ```bash
-   pnpm -C operations exec elevasis-sdk project:list --status active,blocked --format brief
+   pnpm elevasis-sdk project:list --status active --pretty
+   pnpm elevasis-sdk project:list --status blocked --pretty
    ```
 
    Show a compact table: client, status, last-touched.
@@ -154,13 +207,16 @@ No `--prod` flag is needed — the template targets production by default via `E
 
 ### CLI Invocation
 
-All project operations go through the `elevasis-sdk` CLI installed in `operations/`. Run every
-command from the template project root using `-C operations`:
+All project operations go through the `elevasis-sdk` CLI. Use the wrapper script form from the
+project root:
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:<command> [args]
+pnpm elevasis-sdk project:<command> [args]
 ```
 
+The long form `pnpm -C operations exec elevasis-sdk project:<command> [args]` is equivalent and
+still works — use it if the wrapper script is not yet available in an older project.
+
 Organization scoping is handled server-side via `ELEVASIS_PLATFORM_KEY`. No org header or
 `--org` flag is required.
 
@@ -239,7 +295,7 @@ To clear a checklist: `--checklist '[]'`.
 For a plain project table without resume context or next-action suggestions (use the bare `/project` orientation mode above when the user wants the full hub experience):
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:list --kind client_engagement --pretty
+pnpm elevasis-sdk project:list --kind client_engagement --pretty
 ```
 
 Present as:
@@ -261,7 +317,7 @@ For progress detail (milestones/tasks), follow up with `project:milestone:list`
 Wraps `project:work` for fuzzy-matched resume. Used by intent-detection "resume" classification.
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:work <query> --pretty
+pnpm elevasis-sdk project:work <query> --pretty
 ```
 
 Prints the matched project/task brief with current `resume_context`. If multiple matches, show top 3 and ask which.
@@ -274,16 +330,16 @@ If client specified, show full detail for that project. If not, show all.
 
 ```bash
 # Get project details
-pnpm -C operations exec elevasis-sdk project:get <project-id>
+pnpm elevasis-sdk project:get <project-id>
 
 # Milestones (ordered by sequence)
-pnpm -C operations exec elevasis-sdk project:milestone:list --project <project-id> --pretty
+pnpm elevasis-sdk project:milestone:list --project <project-id> --pretty
 
 # Tasks (grouped by milestone)
-pnpm -C operations exec elevasis-sdk project:task:list --project <project-id> --pretty
+pnpm elevasis-sdk project:task:list --project <project-id> --pretty
 
 # Recent notes
-pnpm -C operations exec elevasis-sdk project:note:list --project <project-id> --pretty
+pnpm elevasis-sdk project:note:list --project <project-id> --pretty
 ```
 
 Present as:
@@ -431,21 +487,21 @@ Create everything in sequence using the CLI:
 
 ```bash
 # 1. Create project
-pnpm -C operations exec elevasis-sdk project:create \
+pnpm elevasis-sdk project:create \
   --name "<name>" \
   --kind client_engagement \
   --status active \
   --description "<desc>"
 
 # 2. Create milestones
-pnpm -C operations exec elevasis-sdk project:milestone:create \
+pnpm elevasis-sdk project:milestone:create \
   --project <project-id> \
   --name "<milestone-name>" \
   --status upcoming \
   --due-date <date>
 
 # 3. Create kickoff note (if provided)
-pnpm -C operations exec elevasis-sdk project:note:create \
+pnpm elevasis-sdk project:note:create \
   --project <project-id> \
   --content "<note-content>" \
   --type call_note
@@ -454,7 +510,7 @@ pnpm -C operations exec elevasis-sdk project:note:create \
 If `--company` or `--deal` linking was confirmed, use `project:update` after creation:
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:update <project-id> --description "<updated with link info>"
+pnpm elevasis-sdk project:update <project-id> --description "<updated with link info>"
 ```
 
 (Note: company/deal linking fields are set via the API. If the CLI `project:update` command
@@ -498,7 +554,7 @@ Next: /project status acme
 - `--kind <kind>` (default: `client_engagement`)
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:create \
+pnpm elevasis-sdk project:create \
   --name "<name>" \
   --kind client_engagement \
   --status active \
@@ -514,7 +570,7 @@ pnpm -C operations exec elevasis-sdk project:create \
 First resolve the client (see Client Inference below), then:
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:update <project-id> --status <status>
+pnpm elevasis-sdk project:update <project-id> --status <status>
 ```
 
 ### `milestone add <client> "<name>" [options]` — Add Milestone
@@ -526,7 +582,7 @@ pnpm -C operations exec elevasis-sdk project:update <project-id> --status <statu
 - `--description "<text>"`
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:milestone:create \
+pnpm elevasis-sdk project:milestone:create \
   --project <project-id> \
   --name "<name>" \
   --status upcoming \
@@ -540,13 +596,13 @@ Resolve milestone by name (see Client Inference for project resolution, then use
 
 ```bash
 # List milestones to find ID
-pnpm -C operations exec elevasis-sdk project:milestone:list --project <project-id>
+pnpm elevasis-sdk project:milestone:list --project <project-id>
 
 # Update status
-pnpm -C operations exec elevasis-sdk project:milestone:update <milestone-id> --status completed
+pnpm elevasis-sdk project:milestone:update <milestone-id> --status completed
 
 # Update checklist (full replace)
-pnpm -C operations exec elevasis-sdk project:milestone:update <milestone-id> \
+pnpm elevasis-sdk project:milestone:update <milestone-id> \
   --checklist '[{"id":"uuid","label":"Item label","completed":false}]'
 ```
 
@@ -606,10 +662,10 @@ Onboarding & Scope — Checklist (2/3 complete)
 
 ```bash
 # Resolve milestone ID first if --milestone provided
-pnpm -C operations exec elevasis-sdk project:milestone:list --project <project-id>
+pnpm elevasis-sdk project:milestone:list --project <project-id>
 
 # Create task
-pnpm -C operations exec elevasis-sdk project:task:create \
+pnpm elevasis-sdk project:task:create \
   --project <project-id> \
   --title "<name>" \
   --status planned \
@@ -617,7 +673,7 @@ pnpm -C operations exec elevasis-sdk project:task:create \
   --milestone <milestone-id>
 
 # Create task with initial checklist
-pnpm -C operations exec elevasis-sdk project:task:create \
+pnpm elevasis-sdk project:task:create \
   --project <project-id> \
   --title "<name>" \
   --checklist '[{"id":"1","label":"Step one","completed":false}]'
@@ -629,17 +685,17 @@ Resolve task by name within the project using `project:task:list`, then update b
 
 ```bash
 # Find the task ID
-pnpm -C operations exec elevasis-sdk project:task:list --project <project-id>
+pnpm elevasis-sdk project:task:list --project <project-id>
 
 # Update status (positional <id> comes first, then flags)
-pnpm -C operations exec elevasis-sdk project:task:update <task-id> --status <status>
+pnpm elevasis-sdk project:task:update <task-id> --status <status>
 
 # Update checklist (full replace)
-pnpm -C operations exec elevasis-sdk project:task:update <task-id> \
+pnpm elevasis-sdk project:task:update <task-id> \
   --checklist '[{"id":"uuid","label":"Step","completed":false}]'
 
 # Clear checklist
-pnpm -C operations exec elevasis-sdk project:task:update <task-id> --checklist '[]'
+pnpm elevasis-sdk project:task:update <task-id> --checklist '[]'
 ```
 
 **Options:** `--status`, `--title`, `--milestone`, `--description`, `--checklist <json>`
@@ -663,13 +719,13 @@ If status changes to `approved`, the API auto-sets `completed_at`.
 - `--milestone <milestone-id>` — attach to a milestone (UUID)
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:note:create \
+pnpm elevasis-sdk project:note:create \
   --project <project-id> \
   --content "<content>" \
   --type <type>
 
 # Attach to a task
-pnpm -C operations exec elevasis-sdk project:note:create \
+pnpm elevasis-sdk project:note:create \
   --project <project-id> \
   --content "<content>" \
   --type agent_learning \
@@ -679,7 +735,7 @@ pnpm -C operations exec elevasis-sdk project:note:create \
 ### `notes <client>` — List Notes
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:note:list --project <project-id> --pretty
+pnpm elevasis-sdk project:note:list --project <project-id> --pretty
 ```
 
 ### `delete <client>` — Delete Project
@@ -688,7 +744,7 @@ pnpm -C operations exec elevasis-sdk project:note:list --project <project-id> --
 note count) using the list commands, then ask for confirmation.
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:delete <project-id>
+pnpm elevasis-sdk project:delete <project-id>
 ```
 
 Cascade deletes all milestones, tasks, and notes.
@@ -730,11 +786,12 @@ When in doubt and no project context is resolvable, global auto-memory is the sa
 Before writing a note, the agent resolves which project (and optionally task) to attach it to:
 
 1. **Explicit in session** — a project/task UUID was mentioned or returned by a recent `project:work <id>` or `project:task:*` invocation in this session. Use it directly.
-2. **Implicit from task list** — if step 1 yields nothing, run:
+2. **Implicit from task list** — if step 1 yields nothing, run (`--status` accepts one value; run both calls and merge):
 
    ```bash
-   pnpm -C operations exec elevasis-sdk project:list --status active,blocked --format brief
-   pnpm -C operations exec elevasis-sdk project:task:list --project <top-project-id> --status in_progress
+   pnpm elevasis-sdk project:list --status active --pretty
+   pnpm elevasis-sdk project:list --status blocked --pretty
+   pnpm elevasis-sdk project:task:list --project <top-project-id> --status in_progress
    ```
 
    Use the most-recently-touched project's in-progress task if there is exactly one. If multiple in-progress tasks exist, prefer the one that most closely matches the current conversation topic.
@@ -754,7 +811,7 @@ When the agent recognizes a project-scoped learning (an API quirk, an undocument
 3. Write the note:
 
    ```bash
-   pnpm -C operations exec elevasis-sdk project:note:create \
+   pnpm elevasis-sdk project:note:create \
      --project <project-id> \
      --type agent_learning \
      --task <task-id> \
@@ -792,7 +849,7 @@ When the user or agent says any of the following in the context of a project tas
 Resolve the active task from session context (see Project-Scope Resolution), confirm once ("Mark `<task name>` as completed?"), then fire:
 
 ```bash
-pnpm -C operations exec elevasis-sdk project:task:update <task-id> --status completed
+pnpm elevasis-sdk project:task:update <task-id> --status completed
 ```
 
 If no task resolves, ask the user which task to complete rather than silently skipping.
@@ -817,7 +874,7 @@ Resolve which project the user means using these rules (in priority order):
 1. **Exact ID** — if the argument looks like a UUID, use it directly with `project:get`
 2. **Name match** — list projects filtered by `client_engagement` kind, then match by name:
    ```bash
-   pnpm -C operations exec elevasis-sdk project:list --kind client_engagement
+   pnpm elevasis-sdk project:list --kind client_engagement
    ```
    Filter results by partial name match against the user's input (case-insensitive).
 3. **Single active project** — if only one non-completed `client_engagement` project exists,
@@ -862,7 +919,7 @@ For creating a standard milestone set, run `project:milestone:create` in sequenc
 
 ```bash
 for name in "Discovery" "Implementation" "Testing" "Launch"; do
-  pnpm -C operations exec elevasis-sdk project:milestone:create \
+  pnpm elevasis-sdk project:milestone:create \
     --project <project-id> \
     --name "$name" \
     --status upcoming

package/reference/claude-config/skills/setup/SKILL.md

@@ -1,35 +1,51 @@
 ---
 name: setup
-description: First-time project setup — detect and replace template placeholders, install dependencies, verify build
+description: First-time project setup — detect and replace template placeholders, install dependencies, verify build, then hand off to /configure for org-model configuration
 argument-hint: ""
 ---
 
 # Setup
 
-First-time project setup for projects cloned directly from the template.
+First-time project setup for projects cloned directly from the template. Handles placeholder replacement, dependency install, and build verification. After bootstrap, delegates org-model configuration to `/configure`.
 
 **Usage:** `/setup`
 
-## Process
+---
 
-### Step 1: Detect State
+## State Detection (Run Before Anything Else)
 
-Scan these key files for unresolved placeholders:
+Before collecting any information or running any steps, determine which state the project is in. Read these files:
 
 - `package.json` — look for `__PROJECT_SLUG__` in the `name` field
-- `CLAUDE.md` — look for `TEMPLATE_PROJECT_NAME`
+- `CLAUDE.md` — look for `TEMPLATE_PROJECT_NAME` AND check whether `{CLIENT_CONTEXT}` and `{USER_PREFERENCES}` are still literal placeholder strings
 - `ui/package.json` — look for `__PROJECT_SLUG__`
 - `ui/index.html` — look for `__PROJECT_NAME__`
 
-If NO placeholders are found, the project is already configured. Print:
+**State A — Virgin (placeholders present):** One or more of the above placeholder strings is found. Run the full bootstrap flow (Steps 1–7 below), then hand off to `/configure`.
+
+**State B — Already bootstrapped, org-model at defaults:** No placeholders found, but `foundations/config/organization-model.ts` contains only the default branding override (just `branding.organizationName`, `branding.productName`, `branding.shortName` — no identity, customers, offerings, roles, goals, or techStack overrides). Print:
+
+```
+This project is already set up. The organization model has not been configured yet.
+Running /configure to set up your organization profile...
+```
+
+Then execute `/configure` (the full layered flow) and stop.
+
+**State C — Fully configured:** No placeholders found AND `foundations/config/organization-model.ts` has at least one non-branding domain populated (identity, customers, offerings, roles, goals, or techStack present). Print:
 
 ```
-Project is already configured. Running verification...
+This project is already configured. To update your organization profile, run /configure.
+To re-verify the build, run the checks below.
 ```
 
-Then skip directly to Step 4 (Install) or Step 5 (Verify) as appropriate.
+Offer to run the verification checks (Steps 6b–6e) if the user wants them. Do not re-ask any questions. Do not re-run placeholder replacement. Stop after verification.
+
+---
+
+## Full Bootstrap Flow (State A Only)
 
-### Step 2: Collect Info
+### Step 1: Collect Project Info
 
 Ask the user for three values:
 
@@ -49,7 +65,7 @@ Configuring project with:
 Proceed? (yes/no)
 ```
 
-### Step 3: Get to Know the User and Client
+### Step 2: Get to Know the User and Client
 
 Transition naturally after confirming the project values: "Now let me learn a bit about you and the client so I can be more helpful going forward."
 
@@ -86,7 +102,7 @@ Client: {company}
 Look good?
 ```
 
-### Step 4: Replace Placeholders
+### Step 3: Replace Placeholders
 
 Search ALL files in the project matching these extensions: `.ts`, `.tsx`, `.js`, `.mjs`, `.json`, `.md`, `.mdx`, `.html`, `.yaml`, `.yml`, `.css`, `.env.example`
 
@@ -105,21 +121,19 @@ For each matching file, replace all occurrences of:
 
 Use the Read tool to read each file, then the Edit tool (with `replace_all: true`) or Write tool to apply the replacements. Read each file before writing.
 
-After all replacements, re-scan the four key files from Step 1 to verify zero placeholders remain. If any are still present, report them by file and fix immediately.
+After all replacements, re-scan the four key files from State Detection to verify zero placeholders remain. If any are still present, report them by file and fix immediately.
 
-### Step 5: Populate Knowledge
+### Step 4: Populate CLAUDE.md Knowledge Sections
 
-Knowledge is split between `CLAUDE.md` (essentials loaded every turn) and `docs/knowledge/client.md` (detailed context loaded on demand).
+**Idempotency check (MANDATORY before writing):** Read `CLAUDE.md` and check whether `{CLIENT_CONTEXT}` and `{USER_PREFERENCES}` are still literal placeholder strings. Only write if they are still placeholders. If either section is already filled in (user or a previous run already populated it), skip that section entirely — do not overwrite.
 
-#### 5a: CLAUDE.md — lightweight summary
-
-**`{CLIENT_CONTEXT}`** -- replace with a single line:
+**`{CLIENT_CONTEXT}`** -- replace with a single line (only if still a placeholder):
 
 ```markdown
 **{company name}** — {what they do, one sentence}
 ```
 
-**`{USER_PREFERENCES}`** -- replace with a table:
+**`{USER_PREFERENCES}`** -- replace with a table (only if still a placeholder):
 
 ```markdown
 | Name   | Role   | Technical Level | Communication |
@@ -129,9 +143,11 @@ Knowledge is split between `CLAUDE.md` (essentials loaded every turn) and `docs/
 
 If the user skipped any knowledge questions, fill in what was provided and omit what wasn't -- don't leave placeholder text behind.
 
-#### 5b: docs/knowledge/client.md — full client context
+### Step 5: Create Client Knowledge Doc
+
+**Idempotency check:** Check whether `docs/knowledge/client.md` already exists. If it exists and is non-empty, skip this step entirely -- do not overwrite.
 
-Create `docs/knowledge/client.md` with the detailed info:
+If it does not exist, create `docs/knowledge/client.md`:
 
 ```markdown
 ---
@@ -150,7 +166,9 @@ description: Company background, industry, stakeholders, and business goals
 {any additional context shared -- key stakeholders, business goals, constraints, etc. If nothing was shared, write "No additional context provided yet. Update this as the project evolves."}
 ```
 
-### Step 6: Install Dependencies
+### Step 6: Install and Verify
+
+#### Step 6a: Install Dependencies
 
 ```bash
 pnpm install
@@ -158,7 +176,7 @@ pnpm install
 
 This generates the project's own `pnpm-lock.yaml`. Report success or any errors.
 
-### Step 7: Verify
+#### Step 6b–6e: Verify Build
 
 Run all checks sequentially (stop and report on first failure, but attempt all):
 
@@ -171,7 +189,7 @@ pnpm -C operations check-types
 
 For each check, record PASS or FAIL. If a check fails, read the output and report the error clearly. Do not silently skip failures.
 
-### Step 8: Report
+### Step 7: Bootstrap Report
 
 ```
 You're all set, {name}!
@@ -185,16 +203,23 @@ Verification:
   [PASS/FAIL] Production build (ui)
   [PASS/FAIL] Resource validation (operations)
   [PASS/FAIL] Type-check (operations)
+```
+
+If any verification step failed, add an Errors section listing each failure with its output.
+
+### Step 8: Hand Off to /configure
 
-Next steps:
-1. Copy root .env.example to .env and fill in ELEVASIS_PLATFORM_KEY
-2. Copy ui/.env.example to ui/.env and fill in VITE_WORKOS_CLIENT_ID
-3. See TODO.md for WorkOS dashboard setup and branding
-4. pnpm -C ui dev  (start dev server on port 4300)
-5. (If client-workspace/ exists) Open it in Claude Code and run /setup
+After a successful bootstrap, transition to the org-model configuration flow. Print:
+
+```
+Bootstrap complete. Now let's set up your organization profile.
 ```
 
-If any verification step failed, add an Errors section listing each failure with its output before the Next steps.
+Then execute `/configure` (the full layered flow, no argument). This is where identity, customers, offerings, roles, goals, and techStack are configured. Do not attempt to collect or write org-model data here — that ceremony belongs entirely to /configure.
+
+If the user wants to skip org-model setup for now, they can stop here and run `/configure` later.
+
+---
 
 ## Error Recovery
 
@@ -207,4 +232,28 @@ Remaining: <list files and placeholders>
 Action: Re-applying replacements to affected files...
 ```
 
-Fix each remaining occurrence before proceeding to Step 6.
+Fix each remaining occurrence before proceeding to Step 6a.
+
+---
+
+## Idempotency Guarantees
+
+Running `/setup` more than once is safe:
+
+- **Placeholder replacement** only runs when placeholders are detected (State A). It is skipped entirely in States B and C.
+- **CLAUDE.md knowledge sections** (`{CLIENT_CONTEXT}`, `{USER_PREFERENCES}`) are checked before writing. If already replaced, the write is skipped.
+- **`docs/knowledge/client.md`** is only created if it does not exist. An existing file is never overwritten by `/setup`.
+- **Org-model fields** (`foundations/config/organization-model.ts`) are never written by `/setup`. All org-model edits go through `/configure`, which has its own diff-preview and confirm ceremony.
+
+---
+
+## Relationship to /configure
+
+`/setup` is a thin bootstrap wrapper. It:
+
+1. Replaces scaffold placeholders (project name, slug, description)
+2. Fills lightweight CLAUDE.md knowledge sections (user and client basics, idempotent)
+3. Installs dependencies and verifies the build
+4. Hands off to `/configure` for org-model configuration
+
+`/configure` owns all structural org-model editing (identity, customers, offerings, roles, goals, techStack, features, labels). It is idempotent, confirm-before-overwrite, and includes a runtime validation gate. Re-run `/configure` any time organizational reality changes — no need to re-run `/setup`.