@seliseblocks/cli-os 0.2.7 → 0.2.8

package/dist/skills/blocks-secrets/SKILL.md

@@ -1,81 +1,81 @@
----
-name: blocks-secrets
-description: "Save and retrieve arbitrary named secret values (e.g. captcha provider config, third-party API keys) for a SELISE Blocks project via the blocks CLI's `secrets get`/`secrets save` commands, project-scoped with an impersonated project token. CLI-only surface, no SDK equivalent by design. Storage is generic key/value — shape depends entirely on the secret key, not fixed per type. Use for saving/rotating a secret's key-value pairs or reading one back. `get`'s response is the raw, unredacted value — treat CLI output as sensitive."
----
-
-# Blocks Secrets
-
-This skill manages **generic tenant secret storage** — arbitrary named secret values scoped to a project, via the `blocks secrets *` CLI. It is not tied to any one feature: a project can store a `captcha` secret, an `smtp` secret, or anything else under whatever `secretKey` name it chooses. The shape of the stored value is a flat, caller-defined JSON object (`--key-value-pairs`) — there is no fixed schema across secrets.
-
-**CLI-only, no SDK path, by explicit design.** There is no `@seliseblocks/client` method anywhere for reading or writing tenant secrets (the SDK's only "secret" surfaces are unrelated: MFA enrollment secrets and OIDC `clientSecret`). If a user wants to store or fetch a project secret, `blocks secrets get`/`blocks secrets save` is the only path — don't suggest an SDK call for this.
-
-**Prerequisite:** a project is selected (`blocks use <tenantId>`). If login/project state is unknown, run the blocks-onboarding skill first.
-
-## Command family
-
-Both commands require an **impersonated project token** — there is no account-token path, consistent with `storage config *` and other project-scoped admin surfaces.
-
-| Command | What it does |
-|---|---|
-| `blocks secrets get <secretKey>` | `<secretKey>` positional, or `--secret-key` (required if no positional). Also takes `--page-number` (default `0`) / `--page-size` (default `10`). Read-only. Response is untyped and printed as-is — **not redacted** (see Gotchas). |
-| `blocks secrets save` | Upsert — create or update. Mutating; standard `--dry-run`/`--yes` discipline applies. |
-
-```bash
-blocks secrets get captcha --json
-blocks secrets get --secret-key captcha --page-size 25 --json
-```
-
-The `secretKey` positional argument wins over `--secret-key` if both are somehow given; only one is required. The paging flags imply the response can be a paged list of items filed under that `secretKey`, not necessarily a single flat value — confirm actual shape from what the call returns rather than assuming a single-object response.
-
-## `secrets save` — fields
-
-`save` builds its request body from `--body`/`--file` (a raw JSON object, applied first) merged with these convenience flags (applied second, so they win if both are given):
-
-| Flag | Body field |
-|---|---|
-| `--secret-key` | `secretKey` |
-| `--item-id` | `itemId` |
-| `--key-value-pairs` | `keyValuePairs` |
-
-`--key-value-pairs` takes a JSON **object** string (e.g. `'{"isEnable":"true"}'`) — the CLI rejects arrays or non-objects with `--key-value-pairs must be a JSON object`. Unset convenience flags are dropped, so they never overwrite a field already present in `--body`/`--file`.
-
-```bash
-blocks secrets save --secret-key captcha \
-  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
-  --dry-run --json
-
-blocks secrets save --secret-key captcha \
-  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
-  --yes --json
-
-# Update an existing secret record
-blocks secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json
-```
-
-`save` is create-or-update in one command: omit `--item-id` to create, pass it to update. The captcha example above is only an illustration — `--key-value-pairs` accepts whatever fields the caller's `secretKey` namespace needs.
-
-## `--dry-run` before `--yes` — always
-
-`save` follows the standard `blocks` mutation discipline: passing neither `--dry-run` nor `--yes` drops into an interactive "Type 'yes' to continue" prompt, which is not viable in a scripted/agent context — always pass one explicitly.
-
-- `--dry-run` short-circuits **before** the confirmation prompt and **before any network call**: it prints the resolved request, with a redacted body, and returns.
-- `--yes` skips the interactive prompt and sends the real request.
-
-The dry-run preview's redaction is narrow: it walks `keyValuePairs` only, and replaces the *value* of any entry whose *key* matches a secret-shaped pattern (case-insensitive, e.g. ends in "key," or contains "secret"/"password") with `"***"`. It does **not** touch `secretKey`/`itemId` at the top level, and does **not** touch anything injected via `--body`/`--file` outside `keyValuePairs`. This redaction is preview-only — it never changes what is actually sent when `--yes` is used, and it has no effect on `secrets get`'s response or on the live response from `save` itself.
-
-## Gotchas (secret-handling — read before running either command)
-
-- **`get`'s response is raw and completely unredacted.** The command applies zero masking — the result is passed straight through and printed verbatim. There is no masked/redacted variant of this command. Whatever is stored under that `secretKey` comes back in full, as-is. Treat the output as sensitive: don't repeat the value back to the user beyond what they explicitly asked for, don't paste it into chat/logs/tickets, and never write it into a file that could get committed.
-- **`save`'s live response is also unredacted.** The dry-run preview masks secret-shaped `keyValuePairs` keys, but that's a preview-only convenience. The actual request always sends plaintext values, and whatever comes back is written unredacted too — if the API echoes the saved value back, handle that response with the same care as `get`'s.
-- **This is generic storage, not a captcha-specific feature.** `--key-value-pairs` is a flat JSON object whose fields are entirely defined by whoever picked the `secretKey` — there's no schema registry. Don't assume `isEnable`/`provider`/`captchaKey`/`captchaSecret` apply to a secret that isn't actually a captcha config.
-- **Impersonated project token only, no account-token path.** Both commands require a selected project (`blocks use <tenantId>`) first — same pattern as `storage config *`.
-- **No SDK equivalent exists.** Don't reach for `@seliseblocks/client` for this; the CLI is the only surface, by design.
-- **`save` is upsert, not two verbs.** Whether a call creates or updates is decided by the presence of `--item-id`, not by a different command name.
-
-## Example trigger prompts
-
-- "Save our reCAPTCHA settings as a project secret." → `secrets save --secret-key captcha --key-value-pairs '{...}' --dry-run --json`, confirm, then re-run with `--yes`.
-- "What's stored under the `captcha` secret?" → `secrets get captcha --json` — tell the user the raw stored value will be printed, and don't restate it beyond what they asked for.
-- "Rotate the captcha secret key." → `secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json` (update path — need the existing `itemId`, typically from a prior `secrets get`).
-- "Is there a way to list every secret in the project?" → there's no list-all; `secrets get` requires a `secretKey` and pages within it (`--page-number`/`--page-size`), it doesn't enumerate unknown keys.
-- "Can I read this from my frontend app with the SDK?" → no — `blocks secrets *` is CLI/admin-only; don't scaffold an SDK call, and never put a secret value into frontend code or a committed `.env` file.
+---
+name: blocks-secrets
+description: "Save and retrieve arbitrary named secret values (e.g. captcha provider config, third-party API keys) for a SELISE Blocks project via the blocks CLI's `secrets get`/`secrets save` commands, project-scoped with an impersonated project token. CLI-only surface, no SDK equivalent by design. Storage is generic key/value — shape depends entirely on the secret key, not fixed per type. Use for saving/rotating a secret's key-value pairs or reading one back. `get`'s response is the raw, unredacted value — treat CLI output as sensitive."
+---
+
+# Blocks Secrets
+
+This skill manages **generic tenant secret storage** — arbitrary named secret values scoped to a project, via the `blocks secrets *` CLI. It is not tied to any one feature: a project can store a `captcha` secret, an `smtp` secret, or anything else under whatever `secretKey` name it chooses. The shape of the stored value is a flat, caller-defined JSON object (`--key-value-pairs`) — there is no fixed schema across secrets.
+
+**CLI-only, no SDK path, by explicit design.** There is no `@seliseblocks/client` method anywhere for reading or writing tenant secrets (the SDK's only "secret" surfaces are unrelated: MFA enrollment secrets and OIDC `clientSecret`). If a user wants to store or fetch a project secret, `blocks secrets get`/`blocks secrets save` is the only path — don't suggest an SDK call for this.
+
+**Prerequisite:** a project is selected (`blocks use <tenantId>`). If login/project state is unknown, run the blocks-onboarding skill first.
+
+## Command family
+
+Both commands require an **impersonated project token** — there is no account-token path, consistent with `storage config *` and other project-scoped admin surfaces.
+
+| Command | What it does |
+|---|---|
+| `blocks secrets get <secretKey>` | `<secretKey>` positional, or `--secret-key` (required if no positional). Also takes `--page-number` (default `0`) / `--page-size` (default `10`). Read-only. Response is untyped and printed as-is — **not redacted** (see Gotchas). |
+| `blocks secrets save` | Upsert — create or update. Mutating; standard `--dry-run`/`--yes` discipline applies. |
+
+```bash
+blocks secrets get captcha --json
+blocks secrets get --secret-key captcha --page-size 25 --json
+```
+
+The `secretKey` positional argument wins over `--secret-key` if both are somehow given; only one is required. The paging flags imply the response can be a paged list of items filed under that `secretKey`, not necessarily a single flat value — confirm actual shape from what the call returns rather than assuming a single-object response.
+
+## `secrets save` — fields
+
+`save` builds its request body from `--body`/`--file` (a raw JSON object, applied first) merged with these convenience flags (applied second, so they win if both are given):
+
+| Flag | Body field |
+|---|---|
+| `--secret-key` | `secretKey` |
+| `--item-id` | `itemId` |
+| `--key-value-pairs` | `keyValuePairs` |
+
+`--key-value-pairs` takes a JSON **object** string (e.g. `'{"isEnable":"true"}'`) — the CLI rejects arrays or non-objects with `--key-value-pairs must be a JSON object`. Unset convenience flags are dropped, so they never overwrite a field already present in `--body`/`--file`.
+
+```bash
+blocks secrets save --secret-key captcha \
+  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
+  --dry-run --json
+
+blocks secrets save --secret-key captcha \
+  --key-value-pairs '{"isEnable":"true","provider":"recaptcha","captchaKey":"...","captchaSecret":"..."}' \
+  --yes --json
+
+# Update an existing secret record
+blocks secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json
+```
+
+`save` is create-or-update in one command: omit `--item-id` to create, pass it to update. The captcha example above is only an illustration — `--key-value-pairs` accepts whatever fields the caller's `secretKey` namespace needs.
+
+## `--dry-run` before `--yes` — always
+
+`save` follows the standard `blocks` mutation discipline: passing neither `--dry-run` nor `--yes` drops into an interactive "Type 'yes' to continue" prompt, which is not viable in a scripted/agent context — always pass one explicitly.
+
+- `--dry-run` short-circuits **before** the confirmation prompt and **before any network call**: it prints the resolved request, with a redacted body, and returns.
+- `--yes` skips the interactive prompt and sends the real request.
+
+The dry-run preview's redaction is narrow: it walks `keyValuePairs` only, and replaces the *value* of any entry whose *key* matches a secret-shaped pattern (case-insensitive, e.g. ends in "key," or contains "secret"/"password") with `"***"`. It does **not** touch `secretKey`/`itemId` at the top level, and does **not** touch anything injected via `--body`/`--file` outside `keyValuePairs`. This redaction is preview-only — it never changes what is actually sent when `--yes` is used, and it has no effect on `secrets get`'s response or on the live response from `save` itself.
+
+## Gotchas (secret-handling — read before running either command)
+
+- **`get`'s response is raw and completely unredacted.** The command applies zero masking — the result is passed straight through and printed verbatim. There is no masked/redacted variant of this command. Whatever is stored under that `secretKey` comes back in full, as-is. Treat the output as sensitive: don't repeat the value back to the user beyond what they explicitly asked for, don't paste it into chat/logs/tickets, and never write it into a file that could get committed.
+- **`save`'s live response is also unredacted.** The dry-run preview masks secret-shaped `keyValuePairs` keys, but that's a preview-only convenience. The actual request always sends plaintext values, and whatever comes back is written unredacted too — if the API echoes the saved value back, handle that response with the same care as `get`'s.
+- **This is generic storage, not a captcha-specific feature.** `--key-value-pairs` is a flat JSON object whose fields are entirely defined by whoever picked the `secretKey` — there's no schema registry. Don't assume `isEnable`/`provider`/`captchaKey`/`captchaSecret` apply to a secret that isn't actually a captcha config.
+- **Impersonated project token only, no account-token path.** Both commands require a selected project (`blocks use <tenantId>`) first — same pattern as `storage config *`.
+- **No SDK equivalent exists.** Don't reach for `@seliseblocks/client` for this; the CLI is the only surface, by design.
+- **`save` is upsert, not two verbs.** Whether a call creates or updates is decided by the presence of `--item-id`, not by a different command name.
+
+## Example trigger prompts
+
+- "Save our reCAPTCHA settings as a project secret." → `secrets save --secret-key captcha --key-value-pairs '{...}' --dry-run --json`, confirm, then re-run with `--yes`.
+- "What's stored under the `captcha` secret?" → `secrets get captcha --json` — tell the user the raw stored value will be printed, and don't restate it beyond what they asked for.
+- "Rotate the captcha secret key." → `secrets save --secret-key captcha --item-id <itemId> --key-value-pairs '{...}' --yes --json` (update path — need the existing `itemId`, typically from a prior `secrets get`).
+- "Is there a way to list every secret in the project?" → there's no list-all; `secrets get` requires a `secretKey` and pages within it (`--page-number`/`--page-size`), it doesn't enumerate unknown keys.
+- "Can I read this from my frontend app with the SDK?" → no — `blocks secrets *` is CLI/admin-only; don't scaffold an SDK call, and never put a secret value into frontend code or a committed `.env` file.

package/dist/skills/lint.mjs

@@ -1,168 +1,168 @@
-#!/usr/bin/env node
-// Consistency lint for blocks-skills/. Run: node blocks-skills/lint.mjs
-//
-// A skill is consumed by an AI that has ONLY the globally-installed `blocks`
-// CLI and a project-local `@seliseblocks/client` -- never this monorepo, and
-// `blocks skill add` pulls exactly one skill directory at a time. Checks:
-// 1. Every skill directory has a SKILL.md with frontmatter: `name` matches the
-//    directory name, `name` <= 64 chars, `description` present, non-empty,
-//    on a single physical line (blocks-cli's own frontmatter parser --
-//    src/lib/skills.ts -- is a hand-rolled line-by-line parser with no YAML
-//    dependency; a description that wraps onto a second line silently breaks
-//    `blocks skill list`/`show`), and <= 1024 chars (hard fail) / <= 700 chars
-//    (warn -- this pack's house style target is ~400-600).
-// 2. Relative markdown links (in SKILL.md and any flows/*.md) resolve to a
-//    real file.
-// 3. No links leave the containing skill's own directory at all -- not into
-//    another skill's SKILL.md, not into its flows/, not to a monorepo-only
-//    file outside blocks-skills/. A skill may mention another skill BY NAME
-//    in plain text, never as a link, since the target isn't guaranteed to be
-//    present for a consumer who only pulled this one skill. Links within the
-//    same skill's own directory (SKILL.md <-> its own flows/*.md) are fine.
-// 4. No raw API endpoint paths (e.g. `/iam/v4/...`, `/os/v4/...`) -- skills
-//    describe CLI commands and SDK methods, never the wire protocol behind
-//    them; citing a path is exactly the kind of detail that could tempt a
-//    raw fetch/curl bypass every skill already forbids.
-// Exit 0 = clean, 1 = problems found (all listed, not just the first).
-import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const skillsDir = dirname(fileURLToPath(import.meta.url));
-const errors = [];
-const warnings = [];
-
-const DESCRIPTION_HARD_LIMIT = 1024;
-const DESCRIPTION_WARN_LIMIT = 700;
-const NAME_LIMIT = 64;
-const ENDPOINT_PATTERN = /\/(iam|data|os|logic|release|localization)\/v4\/[A-Za-z0-9/{}._-]*/g;
-
-const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
-  .filter((entry) => entry.isDirectory())
-  .map((entry) => entry.name)
-  .sort();
-
-for (const skillName of skillDirs) {
-  const skillPath = join(skillsDir, skillName);
-  const skillMdPath = join(skillPath, "SKILL.md");
-
-  if (!existsSync(skillMdPath)) {
-    errors.push(`${skillName}/: no SKILL.md`);
-    continue;
-  }
-
-  checkFrontmatter(skillName, skillMdPath);
-  checkLinksInFile(skillName, skillMdPath);
-  checkEndpointsInFile(skillMdPath);
-
-  const flowsDir = join(skillPath, "flows");
-  if (existsSync(flowsDir) && statSync(flowsDir).isDirectory()) {
-    for (const entry of readdirSync(flowsDir, { withFileTypes: true })) {
-      if (entry.isFile() && entry.name.endsWith(".md")) {
-        const flowPath = join(flowsDir, entry.name);
-        checkLinksInFile(skillName, flowPath);
-        checkEndpointsInFile(flowPath);
-      }
-    }
-  }
-}
-
-function checkFrontmatter(skillName, skillMdPath) {
-  const raw = readFileSync(skillMdPath, "utf8");
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
-  const rel = relative(skillsDir, skillMdPath);
-
-  if (!match) {
-    errors.push(`${rel}: missing frontmatter (expected a leading --- ... --- block)`);
-    return;
-  }
-
-  const lines = match[1].split(/\r?\n/);
-  const nameLine = lines.find((line) => line.startsWith("name:"));
-  const descLine = lines.find((line) => line.startsWith("description:"));
-
-  if (!nameLine) {
-    errors.push(`${rel}: frontmatter has no 'name' field`);
-  } else {
-    const name = nameLine.slice("name:".length).trim();
-    if (name !== skillName) {
-      errors.push(`${rel}: name '${name}' does not match directory name '${skillName}'`);
-    }
-    if (name.length > NAME_LIMIT) {
-      errors.push(`${rel}: name is ${name.length} chars, over the ${NAME_LIMIT}-char limit`);
-    }
-  }
-
-  if (!descLine) {
-    errors.push(`${rel}: frontmatter has no 'description' field`);
-    return;
-  }
-
-  const singleLineMatch = descLine.match(/^description:\s*"(.*)"\s*$/);
-  if (!singleLineMatch) {
-    errors.push(
-      `${rel}: 'description' must be a double-quoted string on a single physical line ` +
-        `(blocks-cli's frontmatter parser reads it line-by-line -- a wrapped description silently truncates)`
-    );
-    return;
-  }
-
-  const description = singleLineMatch[1];
-  if (description.length === 0) {
-    errors.push(`${rel}: 'description' is empty`);
-  } else if (description.length > DESCRIPTION_HARD_LIMIT) {
-    errors.push(`${rel}: description is ${description.length} chars, over the ${DESCRIPTION_HARD_LIMIT}-char hard limit`);
-  } else if (description.length > DESCRIPTION_WARN_LIMIT) {
-    warnings.push(`${rel}: description is ${description.length} chars, over the ${DESCRIPTION_WARN_LIMIT}-char house-style target (aim for ~400-600)`);
-  }
-}
-
-function checkLinksInFile(skillName, filePath) {
-  const raw = readFileSync(filePath, "utf8");
-  const rel = relative(skillsDir, filePath);
-  const linkPattern = /\[[^\]]*\]\(([^)]+)\)/g;
-  const fileDir = dirname(filePath);
-
-  for (const match of raw.matchAll(linkPattern)) {
-    const target = match[1].trim();
-    if (/^[a-z]+:\/\//i.test(target) || target.startsWith("#")) continue; // external URL or in-page anchor
-
-    const [pathPart] = target.split("#");
-    if (!pathPart) continue;
-
-    const resolved = join(fileDir, pathPart);
-    if (!existsSync(resolved)) {
-      errors.push(`${rel}: broken link to '${pathPart}' (resolved: ${relative(skillsDir, resolved)})`);
-      continue;
-    }
-
-    const resolvedRelToSkills = relative(skillsDir, resolved).split(/[\\/]/);
-    const targetSkill = resolvedRelToSkills[0];
-    if (targetSkill !== skillName) {
-      errors.push(
-        `${rel}: link leaves this skill's own directory ('${pathPart}') -- ` +
-          `mention other skills by name in plain text instead, never a link, since ` +
-          `'blocks skill add' only copies one skill directory at a time and the target isn't guaranteed to be present`
-      );
-    }
-  }
-}
-
-function checkEndpointsInFile(filePath) {
-  const raw = readFileSync(filePath, "utf8");
-  const rel = relative(skillsDir, filePath);
-
-  for (const match of raw.matchAll(ENDPOINT_PATTERN)) {
-    errors.push(`${rel}: raw API endpoint path '${match[0]}' -- describe the CLI command/SDK method instead, never the wire path`);
-  }
-}
-
-for (const warning of warnings) console.warn(`warning: ${warning}`);
-if (errors.length === 0) {
-  console.log(`ok: ${skillDirs.length} skills, no problems found${warnings.length ? ` (${warnings.length} warning(s) above)` : ""}`);
-  process.exit(0);
-}
-
-console.error(`${errors.length} problem(s) found:`);
-for (const error of errors) console.error(`  - ${error}`);
-process.exit(1);
+#!/usr/bin/env node
+// Consistency lint for blocks-skills/. Run: node blocks-skills/lint.mjs
+//
+// A skill is consumed by an AI that has ONLY the globally-installed `blocks`
+// CLI and a project-local `@seliseblocks/client` -- never this monorepo, and
+// `blocks skill add` pulls exactly one skill directory at a time. Checks:
+// 1. Every skill directory has a SKILL.md with frontmatter: `name` matches the
+//    directory name, `name` <= 64 chars, `description` present, non-empty,
+//    on a single physical line (blocks-cli's own frontmatter parser --
+//    src/lib/skills.ts -- is a hand-rolled line-by-line parser with no YAML
+//    dependency; a description that wraps onto a second line silently breaks
+//    `blocks skill list`/`show`), and <= 1024 chars (hard fail) / <= 700 chars
+//    (warn -- this pack's house style target is ~400-600).
+// 2. Relative markdown links (in SKILL.md and any flows/*.md) resolve to a
+//    real file.
+// 3. No links leave the containing skill's own directory at all -- not into
+//    another skill's SKILL.md, not into its flows/, not to a monorepo-only
+//    file outside blocks-skills/. A skill may mention another skill BY NAME
+//    in plain text, never as a link, since the target isn't guaranteed to be
+//    present for a consumer who only pulled this one skill. Links within the
+//    same skill's own directory (SKILL.md <-> its own flows/*.md) are fine.
+// 4. No raw API endpoint paths (e.g. `/iam/v4/...`, `/os/v4/...`) -- skills
+//    describe CLI commands and SDK methods, never the wire protocol behind
+//    them; citing a path is exactly the kind of detail that could tempt a
+//    raw fetch/curl bypass every skill already forbids.
+// Exit 0 = clean, 1 = problems found (all listed, not just the first).
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const skillsDir = dirname(fileURLToPath(import.meta.url));
+const errors = [];
+const warnings = [];
+
+const DESCRIPTION_HARD_LIMIT = 1024;
+const DESCRIPTION_WARN_LIMIT = 700;
+const NAME_LIMIT = 64;
+const ENDPOINT_PATTERN = /\/(iam|data|os|logic|release|localization)\/v4\/[A-Za-z0-9/{}._-]*/g;
+
+const skillDirs = readdirSync(skillsDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name)
+  .sort();
+
+for (const skillName of skillDirs) {
+  const skillPath = join(skillsDir, skillName);
+  const skillMdPath = join(skillPath, "SKILL.md");
+
+  if (!existsSync(skillMdPath)) {
+    errors.push(`${skillName}/: no SKILL.md`);
+    continue;
+  }
+
+  checkFrontmatter(skillName, skillMdPath);
+  checkLinksInFile(skillName, skillMdPath);
+  checkEndpointsInFile(skillMdPath);
+
+  const flowsDir = join(skillPath, "flows");
+  if (existsSync(flowsDir) && statSync(flowsDir).isDirectory()) {
+    for (const entry of readdirSync(flowsDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith(".md")) {
+        const flowPath = join(flowsDir, entry.name);
+        checkLinksInFile(skillName, flowPath);
+        checkEndpointsInFile(flowPath);
+      }
+    }
+  }
+}
+
+function checkFrontmatter(skillName, skillMdPath) {
+  const raw = readFileSync(skillMdPath, "utf8");
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  const rel = relative(skillsDir, skillMdPath);
+
+  if (!match) {
+    errors.push(`${rel}: missing frontmatter (expected a leading --- ... --- block)`);
+    return;
+  }
+
+  const lines = match[1].split(/\r?\n/);
+  const nameLine = lines.find((line) => line.startsWith("name:"));
+  const descLine = lines.find((line) => line.startsWith("description:"));
+
+  if (!nameLine) {
+    errors.push(`${rel}: frontmatter has no 'name' field`);
+  } else {
+    const name = nameLine.slice("name:".length).trim();
+    if (name !== skillName) {
+      errors.push(`${rel}: name '${name}' does not match directory name '${skillName}'`);
+    }
+    if (name.length > NAME_LIMIT) {
+      errors.push(`${rel}: name is ${name.length} chars, over the ${NAME_LIMIT}-char limit`);
+    }
+  }
+
+  if (!descLine) {
+    errors.push(`${rel}: frontmatter has no 'description' field`);
+    return;
+  }
+
+  const singleLineMatch = descLine.match(/^description:\s*"(.*)"\s*$/);
+  if (!singleLineMatch) {
+    errors.push(
+      `${rel}: 'description' must be a double-quoted string on a single physical line ` +
+        `(blocks-cli's frontmatter parser reads it line-by-line -- a wrapped description silently truncates)`
+    );
+    return;
+  }
+
+  const description = singleLineMatch[1];
+  if (description.length === 0) {
+    errors.push(`${rel}: 'description' is empty`);
+  } else if (description.length > DESCRIPTION_HARD_LIMIT) {
+    errors.push(`${rel}: description is ${description.length} chars, over the ${DESCRIPTION_HARD_LIMIT}-char hard limit`);
+  } else if (description.length > DESCRIPTION_WARN_LIMIT) {
+    warnings.push(`${rel}: description is ${description.length} chars, over the ${DESCRIPTION_WARN_LIMIT}-char house-style target (aim for ~400-600)`);
+  }
+}
+
+function checkLinksInFile(skillName, filePath) {
+  const raw = readFileSync(filePath, "utf8");
+  const rel = relative(skillsDir, filePath);
+  const linkPattern = /\[[^\]]*\]\(([^)]+)\)/g;
+  const fileDir = dirname(filePath);
+
+  for (const match of raw.matchAll(linkPattern)) {
+    const target = match[1].trim();
+    if (/^[a-z]+:\/\//i.test(target) || target.startsWith("#")) continue; // external URL or in-page anchor
+
+    const [pathPart] = target.split("#");
+    if (!pathPart) continue;
+
+    const resolved = join(fileDir, pathPart);
+    if (!existsSync(resolved)) {
+      errors.push(`${rel}: broken link to '${pathPart}' (resolved: ${relative(skillsDir, resolved)})`);
+      continue;
+    }
+
+    const resolvedRelToSkills = relative(skillsDir, resolved).split(/[\\/]/);
+    const targetSkill = resolvedRelToSkills[0];
+    if (targetSkill !== skillName) {
+      errors.push(
+        `${rel}: link leaves this skill's own directory ('${pathPart}') -- ` +
+          `mention other skills by name in plain text instead, never a link, since ` +
+          `'blocks skill add' only copies one skill directory at a time and the target isn't guaranteed to be present`
+      );
+    }
+  }
+}
+
+function checkEndpointsInFile(filePath) {
+  const raw = readFileSync(filePath, "utf8");
+  const rel = relative(skillsDir, filePath);
+
+  for (const match of raw.matchAll(ENDPOINT_PATTERN)) {
+    errors.push(`${rel}: raw API endpoint path '${match[0]}' -- describe the CLI command/SDK method instead, never the wire path`);
+  }
+}
+
+for (const warning of warnings) console.warn(`warning: ${warning}`);
+if (errors.length === 0) {
+  console.log(`ok: ${skillDirs.length} skills, no problems found${warnings.length ? ` (${warnings.length} warning(s) above)` : ""}`);
+  process.exit(0);
+}
+
+console.error(`${errors.length} problem(s) found:`);
+for (const error of errors) console.error(`  - ${error}`);
+process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seliseblocks/cli-os",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "CLI for SELISE Blocks project setup and configuration.",
   "license": "MIT",
   "type": "module",