siesa-agents 2.1.79 → 2.1.81

package/claude/skills/sa-init-observability/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: sa-init-observability
+description: 'Initialize a `.siesa-project` file that consolidates observability metrics across multi-repo logical projects (docs/backend/frontend sub-repos cloned side by side). Use whenever the user wants to set up observability for a new project, mentions `.siesa-project`, asks how to consolidate fragmented `project_id` values in GCP, sees metrics split across `business-*-docs-*`/`business-*-backend-*`/`business-*-frontend-*` repos, or starts working in a project that follows the multi-repo convention. Run this once per logical project, before workflows emit telemetry, so `sa-emit.js` reports a unified `project_id` instead of one per sub-repo.'
+---
+
+# Init Observability — `.siesa-project` Setup
+
+**Goal:** Create a `.siesa-project` file in the correct parent directory so `sa-emit.js` reports a single, stable `project_id` for every workflow that runs inside any sub-repo of the same logical project.
+
+**When this matters:** Projects following the Siesa multi-repo convention split docs, backend and frontend into separate GitHub repos (`business-pos-docs-pdv`, `business-pos-backend-pdv`, `business-pos-frontend-pdv`). Without `.siesa-project`, `sa-emit.js` falls back to `git remote get-url origin` and emits three different `project_id` values for what is conceptually one project. That fragments dashboards in GCP and inflates per-engineer epic counts because the same epic gets counted once per sub-repo it touches.
+
+## When to use this skill
+
+Trigger immediately when the user:
+
+- Says "initialize observability", "set up observability", "init `.siesa-project`", or "configure metrics" for a project
+- Mentions that GCP shows the same engineer/epic across multiple `business-*-docs-*` / `business-*-backend-*` / `business-*-frontend-*` rows
+- Asks how to make several sub-repos report under one logical project name
+- Has just cloned a multi-repo project (e.g. `docs/` + `apps/backend/` + `apps/frontend/`) and is about to run BMAD workflows that emit telemetry
+- References the `.siesa-project` file by name
+
+Do **not** trigger for: editing existing skills, changing OTLP endpoints, debugging a specific event payload (that is `sa-emit.js` territory), or anything unrelated to the `.siesa-project` mechanism.
+
+## Prerequisites
+
+- The user is sitting inside a git repository that belongs to a logical Siesa project (typically a clone of `business-*-{docs|backend|frontend}-*`).
+- Node.js is on the PATH (the scripts are invoked via `node`).
+- Two helper scripts live in the observability scripts dir and are mirrored to the npm copy:
+  - `sa-init-env.js` — ensures `~/.claude/observability/.env` has the OTLP variables sa-emit needs.
+  - `sa-init-project.js` — detects the multi-repo convention and writes `.siesa-project`.
+- Source-of-truth path is `_siesa-agents/observability/scripts/`; the npm mirror is `siesa-agents/observability/scripts/`. Prefer the source-of-truth path when both exist.
+
+If a script is missing, stop and tell the user — do not improvise the logic inline. The scripts are the authoritative source for slug derivation and env scaffolding.
+
+## Workflow
+
+The skill is a three-step orchestration: **ensure global env → detect → write**. Step 0 is idempotent and almost always silent. Steps 1 and 2 do the real work for the `.siesa-project` file.
+
+### Step 0 — Ensure global env
+
+Run `sa-init-env.js` first, every time the skill is invoked:
+
+```bash
+node <observability-scripts>/sa-init-env.js
+```
+
+The script verifies that `~/.claude/observability/.env` exists and declares both `SA_OTLP_ENDPOINT` and `SA_OTLP_HEADERS`. It does **not** modify `sa-emit.js` and does **not** copy values from any project `.env` — it only seeds clearly-fake placeholders that the user must replace before workflows emit real telemetry.
+
+Parse the JSON `status` field:
+
+- **`status: "already-configured"`** — Both variables are already present. Do not mention this to the user unless they explicitly asked about env setup; it is the silent happy path. Continue to Step 1.
+- **`status: "created"`** — The file did not exist; the script wrote a fresh template at `env_path`. Tell the user once: "Created `~/.claude/observability/.env` with placeholder values. Edit it with your real OTLP endpoint and headers before running workflows that emit telemetry." Then continue to Step 1.
+- **`status: "updated"`** — The file existed but was missing one of the two variables; placeholders were appended for `appended_vars`. Tell the user which vars were added and remind them to replace the placeholders. Continue to Step 1.
+- **`status: "error"`** — Surface the error verbatim and stop. Do not proceed to Step 1 — if the env scaffolding is broken, the project-level setup is the wrong place to spend the user's attention.
+
+The placeholders the script writes are intentionally bogus (`https://your-otel-collector.example.com`, `Authorization=Bearer YOUR_TOKEN_HERE`). They will not connect to anything. The user is expected to receive real values from the observability team and paste them in.
+
+### Step 1 — Detect
+
+Run `sa-init-project.js` from the user's current directory (or from any directory inside the target sub-repo if the user told you where they want to initialize):
+
+```bash
+node <observability-scripts>/sa-init-project.js --detect
+```
+
+Parse the JSON object printed to stdout. The `status` field selects the next branch.
+
+**`status: "ready"`** — Multi-repo convention detected. The JSON contains everything needed to act:
+
+- `proposed_slug` — the logical project name to write (e.g. `pos-pdv`)
+- `recommended_dir` — the parent directory chosen by the script (1 level up for `docs` clones, 2 levels up for `backend`/`frontend` clones)
+- `convention_breakdown` — how the slug was derived (`module`, `role`, `rest`)
+
+Proceed straight to Step 2 with `proposed_slug` and `recommended_dir`. Do **not** ask the user to confirm — the user has already accepted the auto-detection policy by invoking this skill.
+
+Single-repo projects also return `status: "ready"` (with `convention_match: false`). The proposed slug is the repo name lowercased and sanitized to kebab-case (e.g. `Siesa-Agents` → `siesa-agents`) and `recommended_dir` is the git root itself. Proceed to Step 2 the same way — no separate branch.
+
+**`status: "already-configured"`** — A `.siesa-project` exists above the current git root. Stop and report `existing_siesa_project.path` and `existing_siesa_project.value` to the user. Do not overwrite implicitly. If the user replies that they want it changed, run `--write` with `--force`, the new slug, and the same directory.
+
+**`status: "no-git-repo"`** — The cwd is not inside a git repo. Tell the user to `cd` into the clone they want to initialize and re-run. Do not invent a directory.
+
+**`status: "no-remote"`** — Git repo without an `origin` remote. Stop and ask the user for a slug + directory before proceeding, since the script has no signal to auto-derive a name.
+
+### Step 2 — Write
+
+When `status == "ready"`, run write immediately with the values from the detect output — no user prompt in between:
+
+```bash
+node <observability-scripts>/sa-init-project.js --write --slug "<proposed_slug>" --dir "<recommended_dir>"
+```
+
+Parse the JSON response:
+
+- **`status: "written"`** — Success. Report a single concise line to the user: the absolute `path` and the slug that was written. Optionally suggest the verification command from Step 3.
+- **`status: "exists"`** — A file is already there with a different value (the detect step missed it because the user pointed at a non-default dir, or a race). Show `current_value` vs `requested_slug` and ask the user whether to overwrite. If yes, re-run with `--force`.
+- **`status: "error"`** — Surface the error message verbatim and stop.
+
+For the `already-configured` and `no-remote` branches where the user explicitly opts into writing, gather slug + directory inline and run the same `--write` command.
+
+The file body written by `--write` is always `project_id=<slug>\n` (key=value form). `sa-emit.js` accepts both this format and a legacy bare-slug line for backward compatibility, so existing `.siesa-project` files keep working.
+
+### Step 3 — Verify (optional)
+
+Suggest the user run a quick sanity check from any sub-repo of the project:
+
+```bash
+node <observability-scripts>/sa-emit.js --event workflow.started --story "0-verify" --phase create-story 2>&1 | grep project_id
+```
+
+If the buffered event shows `project_id=<confirmed-slug>`, the consolidation works. If it still shows the git-remote-derived value, the user is running from a directory that is **not** a descendant of the chosen parent — point them at the right cwd.
+
+## Edge cases
+
+- **Nested logical projects.** If the user runs the skill inside a directory that is already under an existing `.siesa-project`, the script reports `already-configured`. Do not stack `.siesa-project` files — the lowest one wins during walk-up, which can silently mask the consolidation.
+- **Slugs with dots, underscores or uppercase.** The script rejects them. Stick to lowercase + dashes (`pos-pdv`, `finance-billing`). If the user pushes back, explain that GCP labels work best with kebab-case and that other Siesa scripts assume this shape.
+- **Convention without `business-` prefix.** The parser handles both `business-pos-backend-pdv` and a hypothetical `pos-backend-pdv` — both produce `pos-pdv`. Future modules (`finance-*`, `hcm-*`) work without any code change.
+- **Parent dir that is itself a git repo.** Sometimes the docs repo *is* the logical parent (e.g. `comercial/` is a git repo and `comercial/apps/{backend,frontend}/` are clones inside it). That is fine — writing `.siesa-project` in `comercial/` will (a) commit-able in the docs repo, and (b) walked up correctly by `sa-emit.js` from `comercial/apps/backend/`. Mention this to the user so they can decide whether to commit the file (recommended, since it documents the convention for teammates).
+- **Windows path separators.** The script uses `path.join`, so output paths may contain backslashes. Treat them as opaque and pass them back to `--write --dir` verbatim.
+
+## Convention reference
+
+The Siesa multi-repo naming convention is:
+
+```
+business-<module>-<role>-<rest>
+        └ org prefix
+              └ logical module (pos, finance, hcm, …)
+                    └ role: docs | backend | frontend
+                          └ project-specific suffix (pdv, tomapedido, billing, …)
+```
+
+The logical slug collapses `<role>` away: `business-pos-backend-pdv` → `pos-pdv`.
+
+For repo names that do not contain `docs`/`backend`/`frontend`, the script still returns `status: "ready"` but with `convention_match: false`. The slug is derived from the repo name (lowercased, sanitized to kebab-case) and the file is written at the git root of that single repo.
+
+## Examples
+
+**Example 1 — Happy path on a `pos-pdv` clone (env already configured)**
+
+```
+User: I just cloned business-pos-backend-pdv into comercial/apps/backend. Set up observability.
+Model: <runs sa-init-env.js — status "already-configured", silent>
+       <runs sa-init-project.js --detect from comercial/apps/backend/>
+       <reads proposed_slug="pos-pdv", recommended_dir=C:\…\comercial>
+       <runs --write --slug pos-pdv --dir C:\…\comercial without asking>
+       Wrote C:\…\comercial\.siesa-project. sa-emit.js will now report project_id="pos-pdv".
+```
+
+**Example 1b — Same flow on a fresh machine (env missing)**
+
+```
+User: Set up observability for this clone.
+Model: <runs sa-init-env.js — status "created">
+       Created ~/.claude/observability/.env with placeholder values. Edit it with your real OTLP endpoint and headers before running workflows that emit telemetry.
+       <continues with detect + write as in Example 1>
+```
+
+**Example 2 — Single-repo project**
+
+```
+User: Set up .siesa-project for Siesa-Agents.
+Model: <runs sa-init-env.js — silent>
+       <runs --detect from Siesa-Agents/>
+       <reads proposed_slug="siesa-agents", recommended_dir=C:\…\Siesa-Agents, convention_match=false>
+       <runs --write --slug siesa-agents --dir C:\…\Siesa-Agents>
+       Wrote C:\…\Siesa-Agents\.siesa-project (project_id=siesa-agents). sa-emit.js will now report project_id="siesa-agents" instead of "SiesaTeams/Siesa-Agents".
+```
+
+**Example 3 — Already configured**
+
+```
+User: Init observability here.
+Model: <runs --detect>
+       A .siesa-project already exists at C:\…\comercial\.siesa-project with value "pos-pdv". sa-emit.js is already consolidating under that slug. No action needed unless you want to change the value.
+```
+
+## Reminders
+
+- Step 0 (`sa-init-env.js`) always runs first and is idempotent. Skip the user-facing message when its status is `already-configured`; surface it only on `created` / `updated` / `error`.
+- On `status: "ready"` from `sa-init-project.js --detect`, write immediately using `proposed_slug` and `recommended_dir` — no confirmation prompt. The user invoked this skill knowing it auto-creates the file.
+- Never invent a slug. If the detect step returns `single-repo`, `no-remote`, or any branch other than `ready`, stop and let the user drive the next decision.
+- Never call `--write --force` automatically. Overwriting an existing `.siesa-project` always requires an explicit user request.
+- Do not modify `sa-emit.js` or other observability scripts from this skill — its only side effects are (a) creating `~/.claude/observability/.env` with placeholders if absent and (b) creating or overwriting (with consent) a single `.siesa-project` file.
+- The scripts' JSON output is the contract. If a future field appears (e.g. an extra status), surface it to the user rather than guessing what it means.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.79",
+  "version": "2.1.81",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/observability/scripts/sa-emit.js

@@ -134,17 +134,38 @@ const stateDir = path.join(os.homedir(), '.claude', 'observability')
 const epicIdMatch = story.match(/^(\d+)-/)
 const epicId      = epicIdMatch ? epicIdMatch[1] : 'unknown'
 
+function parseSiesaProject(content) {
+  // Preferred format: a single `project_id=<slug>` line. For backward compatibility a bare
+  // slug on its own line is also accepted. `#` introduces a comment. Returns the resolved
+  // slug, or null if nothing usable was found.
+  if (!content) return null
+  let firstBare = null
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq !== -1) {
+      const key = line.slice(0, eq).trim()
+      const val = line.slice(eq + 1).trim()
+      if (key === 'project_id' && val) return val
+      continue
+    }
+    if (firstBare === null) firstBare = line
+  }
+  return firstBare
+}
+
 function findSiesaProject(startDir) {
-  // Walk up from startDir looking for a `.siesa-project` file. Returns its first non-empty
-  // line trimmed, or null. Lets a parent dir override the git-remote-derived project_id —
+  // Walk up from startDir looking for a `.siesa-project` file. Returns the project_id slug
+  // it declares, or null. Lets a parent dir override the git-remote-derived project_id —
   // useful when several sub-repos (docs/backend/frontend) belong to the same logical project.
   let cur = path.resolve(startDir)
   for (let i = 0; i < 40; i++) {
     const candidate = path.join(cur, '.siesa-project')
     if (fs.existsSync(candidate)) {
       try {
-        const first = fs.readFileSync(candidate, 'utf8').split(/\r?\n/)[0].trim()
-        if (first) return first
+        const slug = parseSiesaProject(fs.readFileSync(candidate, 'utf8'))
+        if (slug) return slug
       } catch (_) {}
     }
     const parent = path.dirname(cur)

package/siesa-agents/observability/scripts/sa-init-env.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// sa-init-env.js — Ensure `~/.claude/observability/.env` exists with placeholders for the two
+// OTLP variables the Siesa observability stack needs:
+//   - SA_OTLP_ENDPOINT
+//   - SA_OTLP_HEADERS
+//
+// This script is idempotent. If the file already contains both variables, it exits without
+// touching anything. If the file is missing, it creates it with clearly-fake placeholder
+// values that the user is expected to edit before workflows emit real telemetry. If the file
+// exists but is missing one of the two variables, the missing one is appended — existing
+// values for unrelated keys are preserved exactly.
+//
+// Note: this script does NOT change how sa-emit.js loads configuration. sa-emit.js continues
+// to load only the project-local .env (`process.cwd()/.env`). This script keeps
+// `~/.claude/observability/.env` as a discoverable per-machine template so engineers know
+// which variables they need without having to read sa-emit.js.
+//
+// Modes:
+//   <no args>    Default = --ensure. Creates the file (and parent dir) when needed.
+//   --check      Read-only check. Reports the current state without writing anything.
+//
+// Exit codes:
+//   0  Success (ensure created/updated/no-op, or check ran cleanly)
+//   1  Write or filesystem error
+
+'use strict'
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const TARGET_VARS = ['SA_OTLP_ENDPOINT', 'SA_OTLP_HEADERS']
+
+const PLACEHOLDERS = {
+  SA_OTLP_ENDPOINT: 'https://your-otel-collector.example.com',
+  SA_OTLP_HEADERS:  'Authorization=Bearer YOUR_TOKEN_HERE',
+}
+
+function parseArgs(argv) {
+  const out = {}
+  for (const a of argv) {
+    if (a.startsWith('--')) out[a.slice(2)] = true
+  }
+  return out
+}
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + '\n')
+}
+
+function resolveTarget() {
+  // sa-emit.js uses os.homedir() + '.claude' + 'observability' for its state dir; we mirror
+  // that path so engineers see a single, predictable location across both tools.
+  const dir = path.join(os.homedir(), '.claude', 'observability')
+  const file = path.join(dir, '.env')
+  return { dir, file }
+}
+
+// Parse an existing .env file into an ordered list of entries plus a key index. We track
+// order so we can rewrite the file deterministically without scrambling the user's edits.
+function readEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, lines: [], keys: new Set() }
+  }
+  const raw = fs.readFileSync(filePath, 'utf8')
+  const lines = raw.split(/\r?\n/)
+  const keys = new Set()
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    keys.add(trimmed.slice(0, eq).trim())
+  }
+  return { exists: true, lines, keys, raw }
+}
+
+function findMissingVars(keys) {
+  return TARGET_VARS.filter(v => !keys.has(v))
+}
+
+function buildFreshFile() {
+  return [
+    '# Siesa observability — OTLP exporter configuration.',
+    '# This file is a per-machine template. Replace the placeholder values with the real',
+    '# endpoint and headers you received from the observability team. sa-emit.js itself',
+    '# reads only the project-local .env; this file documents which variables are required',
+    '# and gives you one canonical place to keep your personal copy of them.',
+    '',
+    `SA_OTLP_ENDPOINT=${PLACEHOLDERS.SA_OTLP_ENDPOINT}`,
+    `SA_OTLP_HEADERS=${PLACEHOLDERS.SA_OTLP_HEADERS}`,
+    '',
+  ].join('\n')
+}
+
+function appendMissing(existingRaw, missing) {
+  // Append missing vars at the bottom under a clear delimiter so the user can spot the new
+  // additions and replace the placeholders.
+  const needsLeadingNewline = existingRaw.length > 0 && !existingRaw.endsWith('\n')
+  const parts = [existingRaw]
+  if (needsLeadingNewline) parts.push('\n')
+  parts.push('\n# --- added by sa-init-env.js (placeholders, edit before use) ---\n')
+  for (const v of missing) {
+    parts.push(`${v}=${PLACEHOLDERS[v]}\n`)
+  }
+  return parts.join('')
+}
+
+function runCheck() {
+  const { dir, file } = resolveTarget()
+  const env = readEnvFile(file)
+  if (!env.exists) {
+    emit({
+      status: 'missing',
+      message: `~/.claude/observability/.env does not exist. Run without --check to create it with placeholders.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      present_vars: [],
+      missing_vars: TARGET_VARS.slice(),
+    })
+    return
+  }
+  const missing = findMissingVars(env.keys)
+  if (missing.length === 0) {
+    emit({
+      status: 'already-configured',
+      message: `~/.claude/observability/.env already declares both SA_OTLP_ENDPOINT and SA_OTLP_HEADERS.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      present_vars: TARGET_VARS.slice(),
+      missing_vars: [],
+    })
+    return
+  }
+  emit({
+    status: 'partial',
+    message: `~/.claude/observability/.env exists but is missing: ${missing.join(', ')}. Run without --check to append placeholders for the missing variables.`,
+    env_path: file,
+    env_dir: dir,
+    target_vars: TARGET_VARS,
+    present_vars: TARGET_VARS.filter(v => env.keys.has(v)),
+    missing_vars: missing,
+  })
+}
+
+function runEnsure() {
+  const { dir, file } = resolveTarget()
+
+  if (!fs.existsSync(dir)) {
+    try {
+      fs.mkdirSync(dir, { recursive: true })
+    } catch (err) {
+      emit({ status: 'error', message: `Failed to create ${dir}: ${err.message}`, env_path: file })
+      process.exit(1)
+    }
+  }
+
+  const env = readEnvFile(file)
+
+  if (!env.exists) {
+    try {
+      fs.writeFileSync(file, buildFreshFile(), { encoding: 'utf8' })
+    } catch (err) {
+      emit({ status: 'error', message: `Failed to write ${file}: ${err.message}`, env_path: file })
+      process.exit(1)
+    }
+    emit({
+      status: 'created',
+      message: `Wrote ${file} with placeholder values. Edit the file and replace the placeholders with the real OTLP endpoint and headers before running workflows that emit telemetry.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      wrote_vars: TARGET_VARS.slice(),
+      placeholders: PLACEHOLDERS,
+    })
+    return
+  }
+
+  const missing = findMissingVars(env.keys)
+  if (missing.length === 0) {
+    emit({
+      status: 'already-configured',
+      message: `~/.claude/observability/.env already declares both SA_OTLP_ENDPOINT and SA_OTLP_HEADERS. Nothing to do.`,
+      env_path: file,
+      env_dir: dir,
+      target_vars: TARGET_VARS,
+      present_vars: TARGET_VARS.slice(),
+    })
+    return
+  }
+
+  // File exists but is missing one or more target vars. Append the missing ones with
+  // placeholders; never modify existing entries — the user may have already filled in
+  // real values for the keys that are present.
+  try {
+    fs.writeFileSync(file, appendMissing(env.raw, missing), { encoding: 'utf8' })
+  } catch (err) {
+    emit({ status: 'error', message: `Failed to update ${file}: ${err.message}`, env_path: file })
+    process.exit(1)
+  }
+  emit({
+    status: 'updated',
+    message: `Appended placeholders for missing variables to ${file}: ${missing.join(', ')}. Replace the placeholders with real values before running workflows that emit telemetry.`,
+    env_path: file,
+    env_dir: dir,
+    target_vars: TARGET_VARS,
+    appended_vars: missing,
+    placeholders: PLACEHOLDERS,
+  })
+}
+
+const args = parseArgs(process.argv.slice(2))
+if (args['check']) {
+  runCheck()
+} else {
+  runEnsure()
+}

package/siesa-agents/observability/scripts/sa-init-project.js

@@ -63,6 +63,27 @@ function tryExec(cmd, opts) {
   }
 }
 
+// Parse a `.siesa-project` file body. Preferred format is `project_id=<slug>` (one key=value
+// line, optional `#` comments). For backward compatibility a bare slug on its own line is
+// also accepted. Returns the resolved slug, or null if nothing usable was found.
+function parseSiesaProject(content) {
+  if (!content) return null
+  let firstBare = null
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq !== -1) {
+      const key = line.slice(0, eq).trim()
+      const val = line.slice(eq + 1).trim()
+      if (key === 'project_id' && val) return val
+      continue
+    }
+    if (firstBare === null) firstBare = line
+  }
+  return firstBare
+}
+
 // Walk up from `startDir` looking for an existing `.siesa-project`. Returns
 // { path, value } of the first match found, or null.
 function findExistingSiesaProject(startDir) {
@@ -71,8 +92,8 @@ function findExistingSiesaProject(startDir) {
     const candidate = path.join(cur, '.siesa-project')
     if (fs.existsSync(candidate)) {
       try {
-        const first = fs.readFileSync(candidate, 'utf8').split(/\r?\n/)[0].trim()
-        return { path: candidate, value: first }
+        const value = parseSiesaProject(fs.readFileSync(candidate, 'utf8'))
+        return { path: candidate, value }
       } catch (_) {
         return { path: candidate, value: null }
       }
@@ -186,15 +207,38 @@ function runDetect() {
   const derived = deriveLogicalSlug(repoName)
 
   if (!derived.matched) {
+    // Single-repo project: still write a `.siesa-project` so the project_id is explicit
+    // and self-documented. The slug is derived from the repo name, sanitized to kebab-case,
+    // and the file lands at the git root of the current project.
+    const singleRepoSlug = (repoName || '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+    if (!singleRepoSlug || !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(singleRepoSlug)) {
+      emit({
+        status: 'no-remote',
+        message: 'Could not derive a valid kebab-case slug from the repo name. Pass --slug explicitly to write a .siesa-project.',
+        git_root: gitRoot,
+        remote_url: remoteUrl,
+        remote_repo: repoName,
+      })
+      process.exit(2)
+    }
     emit({
-      status: 'single-repo',
-      message: 'This repo name does not match the multi-repo convention (no docs|backend|frontend segment). sa-emit.js will report project_id based on the git remote, which is already unambiguous for single-repo projects. No .siesa-project is required.',
+      status: 'ready',
+      message: 'Single-repo project detected. The .siesa-project file will be written at the git root with a slug derived from the repo name.',
       git_root: gitRoot,
       remote_url: remoteUrl,
       remote_repo: repoName,
+      convention_match: false,
+      proposed_slug: singleRepoSlug,
+      convention_breakdown: null,
+      parent_candidates: [{ path: gitRoot, label: 'git root', levelsUp: 0 }],
+      recommended_dir: gitRoot,
       fallback_project_id: remoteParsed ? `${remoteParsed.org}/${remoteParsed.repo}` : null,
+      next_step_example: `node sa-init-project.js --write --slug "${singleRepoSlug}" --dir "${gitRoot}"`,
     })
-    process.exit(2)
+    process.exit(0)
   }
 
   const candidates = listParentCandidates(gitRoot)
@@ -256,7 +300,7 @@ function runWrite(args) {
   const target = path.join(resolvedDir, '.siesa-project')
   if (fs.existsSync(target) && !force) {
     let current = null
-    try { current = fs.readFileSync(target, 'utf8').split(/\r?\n/)[0].trim() } catch (_) {}
+    try { current = parseSiesaProject(fs.readFileSync(target, 'utf8')) } catch (_) {}
     emit({
       status: 'exists',
       message: '.siesa-project already exists at this location. Pass --force to overwrite.',
@@ -268,7 +312,7 @@ function runWrite(args) {
   }
 
   try {
-    fs.writeFileSync(target, normalizedSlug + '\n', { encoding: 'utf8' })
+    fs.writeFileSync(target, `project_id=${normalizedSlug}\n`, { encoding: 'utf8' })
   } catch (err) {
     emit({ status: 'error', message: `Failed to write ${target}: ${err.message}` })
     process.exit(3)