@elevasis/sdk 1.5.3 → 1.5.4

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

@@ -0,0 +1,197 @@
+---
+name: save
+description: Auto-manage project documentation and persist task resume context from conversation
+---
+
+# Save
+
+Auto-manage project documentation from conversation context, and fan out conversation signals to the canonical project system (`prj_tasks.resume_context`, `prj_notes`) via the `elevasis-sdk` CLI.
+
+## Canonical Sources of Truth
+
+- **Task resume context (DB):** `prj_tasks.resume_context` is canonical. Agents write it via `elevasis-sdk project:task:save`. Humans edit it via the inline task editor in Command Center. **Never** stash resume context into task-doc frontmatter.
+- **Task-doc frontmatter:** ONLY `title`, `description`, `status`. No `resume_context`, no files-modified, no next-steps arrays -- those belong in the DB.
+- **Project notes (DB):** `prj_notes` via `elevasis-sdk project:note:create`. Typed notes (`status_update` / `issue` / `blocker` / `call_note`) are the durable record of conversation signals.
+
+## Process
+
+### Step 1: Resolve Project + Task Context
+
+Before doing anything else, determine the active project / task:
+
+1. Look for an active task-doc frontmatter in the current conversation or the most recently edited file under `docs/`. Expected frontmatter:
+
+   ```yaml
+   ---
+   title: Short title
+   description: One-line summary
+   status: planned | in-progress | blocked | complete
+   ---
+   ```
+
+2. If the task doc references a project/task UUID anywhere in its body (link, callout, or prior save output), capture those IDs.
+3. If no task / project context is resolvable, PROMPT the user:
+   - "Which project is this work under?" (accepts slug or UUID)
+   - "Is there an existing task I should attach this to? (task UUID, or 'new')"
+
+   Do not guess. Without a task ID, skip Step 4 (DB resume-context save) but still perform Steps 2, 3, 5, 6, 7.
+
+### Step 2: Analyze Conversation
+
+Review the current conversation to identify:
+
+1. **New knowledge** -- architecture decisions, feature implementations, bug fixes, discoveries
+2. **Changed state** -- what was in-progress that is now complete, what new work started
+3. **Stale docs** -- information in existing docs that is now outdated
+4. **Signal events** -- blocker hit, status update worth recording, issue uncovered, call outcome
+5. **OS contract paths touched** -- scan files read/written/edited for any of these signals:
+   - `foundations/config/organization-model.ts` -> Foundations layer, Organization Model
+   - `foundations/types/index.ts` -> Foundations layer, Workflow Contracts
+   - `ui/src/routes/__root.tsx` -> UI Shell Runtime composition
+   - `ui/src/features/**/manifest.ts` or any file defining a `FeatureModule` -> Features layer
+   - `operations/src/index.ts` or `operations/elevasis.config.ts` -> Foundations/Deployment (DeploymentSpec)
+   - Any file inside `ui/src/features/<feature>/` combined with manifest, nav, or sidebar changes -> Features + Toolkit layers
+
+   Record which OS layers were touched: `foundations`, `features`, `shell-runtime`, `toolkit`, `deployment`. If none matched, OS awareness stays dormant for the rest of this run.
+
+### Step 3: Update Knowledge Docs
+
+Scan `docs/` for unindexed or stale knowledge docs and draft creates / updates / moves. All edits are on knowledge/architecture/feature docs -- NOT on task resume state (that flows to the DB in Step 4).
+
+Determine what needs to happen:
+
+- **Create** new docs for significant new knowledge (new features, architecture decisions)
+- **Update** existing docs with corrections, completions, or new details
+- **Move** docs between directories (e.g., `ui/` to `operations/` when ownership shifts)
+- **Delete** docs that are fully obsolete (rare -- prefer updating)
+
+**Frontmatter requirement (all docs in `docs/`):**
+
+```markdown
+---
+title: Short descriptive title
+description: One-line summary of what this doc covers
+---
+```
+
+In-progress task docs additionally require `status`:
+
+```markdown
+---
+title: Feature Name
+description: What this task is about
+status: planned | in-progress | blocked | complete
+---
+```
+
+No other fields. Do NOT add `resume_context`, `files_modified`, or `next_steps` to frontmatter -- those flow to the DB via Step 4.
+
+**Doc structure rules:**
+
+- `docs/ui/` -- frontend features, auth, components, hooks, charts, pages
+- `docs/operations/` -- platform workflows, agents, deployment, resource registry
+- `docs/knowledge/` -- project knowledge, research, reference material, domain context
+- New sections auto-detected -- any subdirectory of `docs/` becomes a section
+- All docs are `.md` (not .mdx)
+- Keep docs focused -- one topic per file
+- Use markdown tables for structured data
+- Include "Last Updated: YYYY-MM-DD" at the bottom of modified docs
+
+**OS layer annotation:** If OS contract paths were touched (Step 2), include an `## Organization OS Impact` section in any newly created architecture doc:
+
+```markdown
+## Organization OS Impact
+
+Touched contracts: [list files]
+Affected layers: [list of layers]
+Cross-reference: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`
+Downstream: template consumer adapters may need review.
+```
+
+Dispatch a `general-purpose` subagent with the plan, conversation context, and these rules. The subagent must read each target file before editing.
+
+### Step 4: Persist Task Resume Context to DB
+
+If Step 1 resolved a task ID, save the current state to `prj_tasks.resume_context` via the SDK CLI. This is the canonical persistence step and must run every `/save` invocation that has a task in scope:
+
+```bash
+pnpm exec elevasis-sdk project:task:save <task-uuid> \
+  --current-state "<concise prose summary of where we are>" \
+  --next-steps "<concise prose of the next concrete action>" \
+  --files-modified '["path/one.ts","path/two.tsx"]' \
+  --key-docs '["docs/knowledge/foo.md"]' \
+  --tools '["project:task:save","project:note:create"]'
+```
+
+Arg rules:
+
+- `--current-state` (required) -- terse, present-tense "what is true right now". Prefer latest state over accumulated history.
+- `--next-steps` -- single next concrete action another agent could execute without re-deriving intent.
+- `--files-modified` -- JSON array of uncommitted / just-changed file paths (relative to project root).
+- `--key-docs` -- JSON array of doc paths an agent should re-read to resume.
+- `--tools` -- JSON array of tool / CLI names used this session that are worth flagging.
+
+The endpoint is `PATCH /api/external/tasks/<id>/resume-context` and merges (does not replace) provided fields. Omit any arg that has nothing meaningful to record.
+
+### Step 5: Create Typed Project Notes on Signal Events
+
+For each signal event identified in Step 2, create a typed `prj_note`. One CLI call per note:
+
+```bash
+pnpm exec elevasis-sdk project:note:create \
+  --project <project-uuid> \
+  --task <task-uuid>          # optional, omit if not scoped to a task \
+  --type <note-type> \
+  --content "<what happened, why it matters, any next action>"
+```
+
+Note-type mapping (use the first type that matches, in this order):
+
+- **`blocker`** -- work cannot proceed without external action (decision, credential, fix elsewhere, upstream change). Always create if detected. Trigger phrases: "I'm stuck", "blocked on", "can't proceed until", "waiting on <X>". When detected AND a task ID is in scope, ALSO fire a status transition -- see Step 5a below.
+- **`issue`** -- bug, regression, unexpected failure, contract mismatch. Include reproduction context in `--content`.
+- **`status_update`** -- milestone-level progress worth flagging to the human operator (phase complete, substantial deliverable landed, direction change). Keep it substantive -- `/save` runs shouldn't emit a status_update every turn.
+- **`call_note`** -- only if the conversation is transcribing a live client / stakeholder call.
+
+If no signal rises to note-worthy, skip this step entirely. Do not create filler notes.
+
+### Step 5a: Blocker Signal -> Task Status Transition
+
+Run this ONLY when Step 5 created a `blocker` note AND Step 1 resolved a task ID. It's the second half of the "I'm stuck" fanout: the note captures the why, this call flips the task's lifecycle state so it surfaces as blocked in portfolio views.
+
+```bash
+pnpm -C operations exec elevasis-sdk project:task:update <task-uuid> --status blocked
+```
+
+Rules:
+
+- **Explicit task ID only** -- use the UUID resolved in Step 1. Do not re-derive or guess. If no task is in scope, skip this step (the blocker note still ships without it).
+- **Best-effort** -- if the CLI returns non-2xx, surface a single warning line in Step 7 ("Warning: could not transition task <id> to blocked: <reason>") and continue. Do not retry, do not block the rest of `/save`.
+- **Idempotent** -- if the task is already `blocked`, the update is a no-op. Fire it anyway; do not pre-check.
+- **Order** -- the `blocker` note (Step 5) creates first; this transition follows. Keeps the note attached to the task even if the status update later fails.
+
+### Step 6: Regenerate Docs Index
+
+After the Step 3 subagent completes all doc file changes, regenerate `docs/index.md`:
+
+```bash
+pnpm exec elevasis-sdk generate-docs
+```
+
+This deterministically scans `docs/`, reads frontmatter, and rebuilds the navigation hub. Never edit `docs/index.md` manually.
+
+### Step 7: Report
+
+Summarize:
+
+- Knowledge docs created / updated / moved / deleted
+- Task ID written to (Step 4): `resume_context.last_saved` timestamp from the CLI response
+- Notes created (Step 5): count, types, IDs
+- OS classification (if applicable): layers detected, contracts touched
+- Any files skipped due to missing frontmatter (Step 3 subagent should have added it)
+- Any follow-ups for the human operator
+
+## Failure Modes
+
+- **No task in scope + user declines to provide one:** proceed with Steps 2, 3, 6, 7; skip Step 4; still allow Step 5 if a `--project` UUID is available.
+- **`project:task:save` returns non-2xx:** surface the error in the report, do not retry silently; Step 5 and Step 6 still run.
+- **`generate-docs` fails:** surface the error; doc edits from Step 3 are already on disk, so they are not lost -- the operator can re-run the index regeneration manually.

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

@@ -0,0 +1,210 @@
+---
+name: setup
+description: First-time project setup — detect and replace template placeholders, install dependencies, verify build
+argument-hint: ""
+---
+
+# Setup
+
+First-time project setup for projects cloned directly from the template.
+
+**Usage:** `/setup`
+
+## Process
+
+### Step 1: Detect State
+
+Scan these key files for unresolved placeholders:
+
+- `package.json` — look for `__PROJECT_SLUG__` in the `name` field
+- `CLAUDE.md` — look for `TEMPLATE_PROJECT_NAME`
+- `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:
+
+```
+Project is already configured. Running verification...
+```
+
+Then skip directly to Step 4 (Install) or Step 5 (Verify) as appropriate.
+
+### Step 2: Collect Info
+
+Ask the user for three values:
+
+1. **Slug** — lowercase, hyphens only (e.g., `acme-dashboard`). Default to the basename of the current working directory.
+2. **Human-readable name** — used in titles, docs, and CLAUDE.md (e.g., `Acme Dashboard`).
+3. **Short description** — one sentence, used in `package.json` and CLAUDE.md (e.g., `Client dashboard for Acme Corp.`).
+
+Confirm the values before proceeding:
+
+```
+Configuring project with:
+  Slug:        <slug>
+  Name:        <name>
+  Description: <description>
+  Date:        <YYYY-MM-DD>
+
+Proceed? (yes/no)
+```
+
+### Step 3: 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."
+
+**About the user (ask conversationally, one at a time):**
+
+1. **Name** -- "What's your first name?"
+2. **Role** -- "What's your role?" (e.g., founder, developer, project lead)
+3. **Technical level** -- "How comfortable are you with technical stuff? No wrong answer -- just helps me know how to explain things."
+4. **Communication style** -- "When I explain things or write docs, do you prefer short and to-the-point, or more detailed with context?"
+
+Use their name naturally from this point on.
+
+**About the client/company this project is for:**
+
+5. **Company name** -- "Who's this project for? What's the company name?"
+6. **What they do** -- "What does {company} do? Just a sentence or two."
+7. **Industry** -- "What industry or space are they in?"
+8. **Key context** -- "Anything else that would help me understand the project context? Key stakeholders, business goals, important constraints -- whatever comes to mind. (Totally fine to skip, we can add this as we go.)"
+
+React to what they share, ask natural follow-ups if something is interesting or unclear. Don't make it feel like a form.
+
+After gathering, confirm:
+
+```
+Got it! Here's what I captured:
+
+User: {name} ({role}, {technical level}, prefers {style})
+
+Client: {company}
+  {what they do}
+  Industry: {industry}
+  {any additional context}
+
+Look good?
+```
+
+### Step 4: Replace Placeholders
+
+Search ALL files in the project matching these extensions: `.ts`, `.tsx`, `.js`, `.mjs`, `.json`, `.md`, `.mdx`, `.html`, `.yaml`, `.yml`, `.css`, `.env.example`
+
+Exclude these directories and files: `node_modules/`, `dist/`, `.tanstack/`, `pnpm-lock.yaml`
+
+For each matching file, replace all occurrences of:
+
+| Placeholder                    | Replace with            |
+| ------------------------------ | ----------------------- |
+| `__PROJECT_NAME__`             | human-readable name     |
+| `__PROJECT_SLUG__`             | slug                    |
+| `__PROJECT_DESCRIPTION__`      | description             |
+| `__DATE__`                     | today's date YYYY-MM-DD |
+| `TEMPLATE_PROJECT_NAME`        | human-readable name     |
+| `TEMPLATE_PROJECT_DESCRIPTION` | description             |
+
+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.
+
+### Step 5: Populate Knowledge
+
+Knowledge is split between `CLAUDE.md` (essentials loaded every turn) and `docs/knowledge/client.md` (detailed context loaded on demand).
+
+#### 5a: CLAUDE.md — lightweight summary
+
+**`{CLIENT_CONTEXT}`** -- replace with a single line:
+
+```markdown
+**{company name}** — {what they do, one sentence}
+```
+
+**`{USER_PREFERENCES}`** -- replace with a table:
+
+```markdown
+| Name   | Role   | Technical Level | Communication |
+| ------ | ------ | --------------- | ------------- |
+| {name} | {role} | {level}         | {preference}  |
+```
+
+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
+
+Create `docs/knowledge/client.md` with the detailed info:
+
+```markdown
+---
+title: Client Context
+description: Company background, industry, stakeholders, and business goals
+---
+
+# Client Context
+
+**Company:** {company name}
+**Industry:** {industry}
+**Description:** {what they do}
+
+## Additional Context
+
+{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
+
+```bash
+pnpm install
+```
+
+This generates the project's own `pnpm-lock.yaml`. Report success or any errors.
+
+### Step 7: Verify
+
+Run all checks sequentially (stop and report on first failure, but attempt all):
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui build
+pnpm -C operations check
+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
+
+```
+You're all set, {name}!
+========================
+Project: <Human Name>
+Slug:    <slug>
+Client:  <company name> (<industry>)
+
+Verification:
+  [PASS/FAIL] Type-check (ui)
+  [PASS/FAIL] Production build (ui)
+  [PASS/FAIL] Resource validation (operations)
+  [PASS/FAIL] Type-check (operations)
+
+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
+```
+
+If any verification step failed, add an Errors section listing each failure with its output before the Next steps.
+
+## Error Recovery
+
+If placeholder replacement leaves stragglers:
+
+```
+Placeholder Cleanup Required
+=============================
+Remaining: <list files and placeholders>
+Action: Re-applying replacements to affected files...
+```
+
+Fix each remaining occurrence before proceeding to Step 6.

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

@@ -0,0 +1,60 @@
+---
+name: status
+description: Quick project health check
+---
+
+# Status
+
+Quick project health check.
+
+**Usage:** `/status`
+
+## Process
+
+### Step 1: Gather Data
+
+Run in parallel:
+
+1. `git status` - working tree state
+2. `git log --oneline -5` - recent commits
+3. `pnpm test` - test results
+4. `pnpm lint` - type check
+
+### Step 2: Check Docs + Active Work
+
+1. Read `docs/index.md` - verify doc structure is current
+2. Query active project work via `pnpm -C operations exec elevasis-sdk project:list --status active,blocked --format brief` - active project/task count lives in the DB, not in `docs/in-progress/`
+
+### Step 3: Report
+
+```
+Project Status
+==============
+
+Git
+---
+Branch: <branch>
+Clean: Yes/No (N uncommitted changes)
+Last commit: <hash> - <message> (<date>)
+
+Tests
+-----
+Result: All passing / N failures
+Details: [if failures, list them]
+
+Types
+-----
+Result: Clean / N errors
+Details: [if errors, list them]
+
+Docs
+----
+Architecture: N docs
+Features: N docs
+
+Active Work (DB)
+----------------
+Projects: N active, N blocked
+  - [client 1] (status)
+  - [client 2] (status)
+```

package/reference/claude-config/skills/submit-issue/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: submit-issue
+description: Submit a structured issue report to the Elevasis platform via API — enforces pre-analysis before posting
+---
+
+# Submit Issue
+
+Submit a structured issue report to the Elevasis platform. The agent performs a six-phase analysis before posting so that every submitted issue includes meaningful context, not just a one-liner.
+
+**Usage:** `/submit-issue [optional description]`
+
+If a description is provided, it is the primary signal for Phase 1. Otherwise the agent analyzes recent conversation context (~20 messages) plus any active error context.
+
+## Env Requirements
+
+Both variables must be present in the project's root `.env`:
+
+| Variable           | Description                                                                                   |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| `ELEVASIS_API_URL` | Platform API base URL (e.g. `https://api.elevasis.io`)                                        |
+| `ELEVASIS_API_KEY` | API key starting with `sk_` (67 chars), provisioned from Command Center > Settings > API Keys |
+
+The organization is resolved server-side from the key. Never include an `organization_id` in the request body.
+
+## Pre-Analysis Phases
+
+Complete all six phases before assembling the report or asking for confirmation. Do not skip phases — they ensure the submitted record is actionable.
+
+### Phase 1: Collect Context
+
+Gather available context:
+
+- If the user provided a description with the command, treat it as the primary signal.
+- Otherwise review the last ~20 conversation messages for error output, failed commands, unexpected behavior, and any `explain_page` / active error context.
+- Ask one targeted follow-up question if a key detail is ambiguous. Do not fire multiple questions at once.
+
+### Phase 2: Identify Source
+
+Pinpoint where the issue originates:
+
+- File paths (if a code or config file is involved)
+- Workflow or agent resource IDs (if a platform execution failed)
+- Execution IDs (if available in logs or prior output)
+- Route or page path (if a UI issue)
+
+Record these for the `evidence` and `affected_page` fields.
+
+### Phase 3: Gather Errors
+
+Extract concrete error signals:
+
+- Full error messages and stack traces (truncated to the relevant portion)
+- HTTP status codes and response bodies
+- Log lines with timestamps if available
+- Screenshots or screenshot file references if the user provided them
+
+These go into the `evidence` object.
+
+### Phase 4: Classify Severity and Category
+
+Select exactly one value for each:
+
+**Severity:**
+
+| Value      | When to use                                                         |
+| ---------- | ------------------------------------------------------------------- |
+| `critical` | Data loss, security breach, complete feature outage, blocked deploy |
+| `warning`  | Degraded behavior, partial failure, noticeable but recoverable      |
+| `info`     | Minor UX glitch, cosmetic bug, improvement suggestion               |
+
+**Category:**
+
+| Value                | When to use                                            |
+| -------------------- | ------------------------------------------------------ |
+| `ui_bug`             | Frontend rendering or interaction problem              |
+| `data_inconsistency` | DB records, API responses, or UI state don't match     |
+| `performance`        | Slow load, timeout, high resource usage                |
+| `error_pattern`      | Recurring or systematic error across executions        |
+| `configuration`      | Misconfigured resource, credential, env var, or policy |
+| `other`              | Doesn't fit above                                      |
+
+### Phase 5: Build Structured Report
+
+Assemble the request body from phases 1–4:
+
+```json
+{
+  "title": "One-line summary — specific, not vague",
+  "description": "What happened. What was expected. Steps to reproduce if applicable.",
+  "severity": "<critical|warning|info>",
+  "category": "<category value>",
+  "affected_page": "<route or page path, omit if not a UI issue>",
+  "evidence": {
+    "errors": ["<error message or stack trace excerpt>"],
+    "log_snippets": ["<relevant log lines>"],
+    "screenshot_refs": ["<file path if user provided a screenshot>"]
+  },
+  "context": {
+    "source_files": ["<file paths>"],
+    "resource_ids": ["<workflow or agent IDs>"],
+    "execution_ids": ["<execution IDs>"],
+    "summary": "<one-paragraph agent analysis summary>"
+  }
+}
+```
+
+Omit any field that has nothing meaningful to record. `project_id` and `task_id` are optional UUID fields — include them only if the issue is clearly scoped to a specific project or task visible in context.
+
+### Phase 6: Confirm with User
+
+Unless the command was invoked with `--auto`, present the assembled report to the user before submitting:
+
+```
+Issue Report (ready to submit)
+================================
+Title:    <title>
+Severity: <severity>
+Category: <category>
+Page:     <affected_page or "—">
+
+Description:
+  <description>
+
+Evidence:
+  <summarized evidence>
+
+Context:
+  <summarized context>
+
+Submit? (yes / edit / cancel)
+```
+
+If the user says "edit", accept corrections and re-display the updated report before proceeding.
+If the user says "cancel", abort and confirm: "Submission cancelled."
+Auto-submit (`--auto`) skips this confirmation entirely — use only when the caller is a trusted agent pipeline.
+
+## Submit
+
+Once confirmed (or `--auto`), POST to the external issues endpoint:
+
+```bash
+curl -sS -X POST "${ELEVASIS_API_URL}/api/external/issues" \
+  -H "Authorization: Bearer ${ELEVASIS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d @- <<'JSON'
+{
+  "title": "...",
+  "description": "...",
+  "severity": "warning",
+  "category": "ui_bug",
+  "affected_page": "/projects/abc",
+  "evidence": {},
+  "context": {}
+}
+JSON
+```
+
+Do NOT include `source` or `organization_id` in the body — the server sets both automatically.
+
+## Report Back
+
+On a successful response (2xx), surface the issue ID to the user:
+
+```
+Submitted — id: <uuid>
+Track it in Command Center > Issues.
+```
+
+If the response body contains additional fields (status, created_at), include them in a brief one-line summary.
+
+## Troubleshooting
+
+| Status             | Cause                                                             | Fix                                                                                                                                           |
+| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `401 Unauthorized` | `ELEVASIS_API_KEY` is missing, malformed, or revoked              | Verify the key in root `.env` starts with `sk_` and is 67 chars. Re-provision from Command Center > Settings > API Keys if needed.            |
+| `403 Forbidden`    | Key exists but the associated org lacks access to issue reporting | Contact the platform operator to verify the key's org permissions.                                                                            |
+| `400 Bad Request`  | Request body failed validation                                    | Read the response body for the specific field error. Common causes: missing `title` or `description`, invalid `severity` or `category` value. |
+| `404 Not Found`    | `ELEVASIS_API_URL` is wrong or the endpoint path has a typo       | Confirm the URL in `.env` (no trailing slash) and that the path is exactly `/api/external/issues`.                                            |
+| Connection refused | API server unreachable                                            | Check `ELEVASIS_API_URL` and network connectivity. For local dev, confirm the API server is running.                                          |