destinotes-skills 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Destinotes contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# destinotes-skills
+
+Agent skills that generate repository documentation under `./destinotes/`. Works with **Cursor** and **Claude Code**.
+
+## Install
+
+From any project directory:
+
+```bash
+npx destinotes-skills
+```
+
+This runs an **interactive setup** that walks you through:
+
+- Project name (auto-detected from `package.json` or folder name)
+- Repository URL (auto-detected from `git remote origin` when possible)
+- Default branch
+- Docs output folder (default: `./destinotes/`)
+- Which agents to install to (Cursor, Claude Code)
+- Project-level vs global skill install
+
+Settings are saved to `./destinotes/destinotes.config.json`. Skills are copied into `.cursor/skills/` and/or `.claude/skills/`.
+
+### Non-interactive / CI
+
+```bash
+npx destinotes-skills install -y          # skip prompts, use detected defaults
+npx destinotes-skills -g -y               # global install, no prompts
+npx destinotes-skills -a cursor -y        # Cursor only
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `setup` | Interactive setup + install (default) |
+| `install` | Install skills only, skip project prompts (use with `-y`) |
+
+## Skills
+
+| Skill | Invocation | Output |
+|-------|------------|--------|
+| `destinotes-prompt` | (parent contract; always active) | — |
+| `destinotes-general` | `/destinotes-general` | `./destinotes/<category>/*.md` |
+| `destinotes-feature` | `/destinotes-feature <slug> <context>` | `./destinotes/features/<slug>.md` |
+| `destinotes-document` | `/destinotes-document <folder>:<file> <context>` | `./destinotes/<folder>/<file>.md` |
+| `destinotes-cost-analysis` | `/destinotes-cost-analysis <slug> <context>` | `./destinotes/cost-analysis/<slug>.md` |
+
+## Publish
+
+```bash
+cd packages/skills
+npm login
+npm publish --access public
+```
+
+## Development
+
+Skill source of truth lives in `packages/skills/skills/`. To sync into this app's Claude skills for local dev:
+
+```bash
+node packages/skills/scripts/sync-to-claude.mjs
+```

package/bin/install.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readConfig } from "./lib/config.mjs";
+import { finalizeProjectFiles, runSetup } from "./setup.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+const SKILLS_SOURCE = join(PACKAGE_ROOT, "skills");
+
+const AGENTS = {
+  cursor: {
+    label: "Cursor",
+    projectDir: ".cursor/skills",
+    globalDir: join(homedir(), ".cursor", "skills"),
+  },
+  claude: {
+    label: "Claude Code",
+    projectDir: ".claude/skills",
+    globalDir: join(homedir(), ".claude", "skills"),
+  },
+};
+
+const AGENT_LABELS = Object.fromEntries(
+  Object.entries(AGENTS).map(([id, agent]) => [id, agent.label]),
+);
+
+function parseArgs(argv) {
+  const options = {
+    command: "setup",
+    global: false,
+    yes: false,
+    agents: null,
+    help: false,
+    cwd: process.cwd(),
+  };
+
+  const args = [...argv];
+
+  if (args[0] && !args[0].startsWith("-")) {
+    options.command = args.shift();
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-g" || arg === "--global") {
+      options.global = true;
+    } else if (arg === "-y" || arg === "--yes") {
+      options.yes = true;
+    } else if (arg === "--cwd") {
+      options.cwd = args[i + 1];
+      i += 1;
+    } else if (arg === "-a" || arg === "--agents") {
+      options.agents = (args[i + 1] ?? "")
+        .split(",")
+        .map((name) => name.trim())
+        .filter(Boolean);
+      i += 1;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`destinotes-skills — install Destinotes agent skills
+
+Usage:
+  npx destinotes-skills [command] [options]
+
+Commands:
+  setup     Interactive setup + install (default)
+  install   Install skills only, skip project prompts (-y)
+
+Options:
+  -g, --global          Install to user-level skill dirs
+  -a, --agents <list>   Comma-separated agents: cursor, claude
+  --cwd <path>          Project directory (default: cwd)
+  -y, --yes             Skip interactive prompts
+  -h, --help            Show this help
+
+Interactive setup configures:
+  - Project name
+  - Repository URL (auto-detected from git remote when possible)
+  - Default branch
+  - Docs output folder (default: ./destinotes/)
+  - Agent targets (Cursor, Claude Code)
+  - Project vs global skill install
+
+Config is saved to ./destinotes/destinotes.config.json (or your chosen docs folder).
+
+Skills installed:
+  destinotes-prompt, destinotes-general, destinotes-feature,
+  destinotes-document, destinotes-cost-analysis
+`);
+}
+
+function listSkillNames() {
+  return readdirSync(SKILLS_SOURCE, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function detectAgents(cwd, global) {
+  const detected = [];
+
+  for (const [id, agent] of Object.entries(AGENTS)) {
+    if (global) {
+      const parent = dirname(agent.globalDir);
+      if (existsSync(parent) || existsSync(agent.globalDir)) {
+        detected.push(id);
+      }
+      continue;
+    }
+
+    const projectMarker = join(cwd, agent.projectDir.split("/")[0]);
+    if (existsSync(projectMarker)) {
+      detected.push(id);
+    }
+  }
+
+  return detected.length > 0 ? detected : ["cursor", "claude"];
+}
+
+function resolveTargetDirs(agentId, cwd, global) {
+  const agent = AGENTS[agentId];
+  if (!agent) {
+    throw new Error(`Unknown agent: ${agentId}. Use cursor or claude.`);
+  }
+
+  const base = global ? agent.globalDir : join(cwd, agent.projectDir);
+  return { agent, base };
+}
+
+function installSkills(targetBase, skillNames) {
+  mkdirSync(targetBase, { recursive: true });
+
+  for (const skillName of skillNames) {
+    const source = join(SKILLS_SOURCE, skillName);
+    const destination = join(targetBase, skillName);
+    cpSync(source, destination, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.command !== "setup" && options.command !== "install") {
+    console.error(`Unknown command: ${options.command}`);
+    printHelp();
+    process.exit(1);
+  }
+
+  const skillNames = listSkillNames();
+  if (skillNames.length === 0) {
+    console.error("No skills found in package. Is the install corrupted?");
+    process.exit(1);
+  }
+
+  const detectedAgents = detectAgents(options.cwd, options.global);
+  const skipSetup = options.command === "install" || options.yes;
+
+  const existingConfig = readConfig(options.cwd);
+  const config = await runSetup({
+    cwd: options.cwd,
+    global: options.global,
+    yes: skipSetup,
+    agents: options.agents,
+    detectedAgents,
+    agentLabels: AGENT_LABELS,
+  });
+
+  const agentIds = config.agents ?? options.agents ?? detectedAgents;
+  const installGlobal = config.global ?? options.global;
+  const invalidAgents = agentIds.filter((id) => !AGENTS[id]);
+
+  if (invalidAgents.length > 0) {
+    console.error(`Unknown agent(s): ${invalidAgents.join(", ")}`);
+    process.exit(1);
+  }
+
+  for (const agentId of agentIds) {
+    const { agent, base } = resolveTargetDirs(agentId, options.cwd, installGlobal);
+    installSkills(base, skillNames);
+    console.log(`✓ ${agent.label}: ${base}`);
+    for (const skillName of skillNames) {
+      console.log(`  · ${skillName}`);
+    }
+  }
+
+  if (!installGlobal) {
+    const docs = finalizeProjectFiles(options.cwd, config, existingConfig);
+    if (docs) {
+      console.log(`✓ Config: ${docs.configPath}`);
+      if (docs.readmeCreated) {
+        console.log(`✓ Created ${docs.readmePath}`);
+      } else {
+        console.log(`✓ Docs folder: ${docs.readmePath.replace(/README\.md$/, "")}`);
+      }
+    }
+  }
+
+  console.log("\nDone. Try /destinotes-general in your agent.");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/bin/lib/config.mjs

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CONFIG_VERSION = 1;
+export const CONFIG_FILENAME = "destinotes.config.json";
+
+export function getConfigPath(cwd, docsDir) {
+  return join(cwd, docsDir, CONFIG_FILENAME);
+}
+
+export function readConfig(cwd, docsDir = "destinotes") {
+  const configPath = getConfigPath(cwd, docsDir);
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeConfig(cwd, config) {
+  const docsDir = config.docsDir ?? "destinotes";
+  const destinotesDir = join(cwd, docsDir);
+  mkdirSync(destinotesDir, { recursive: true });
+
+  const configPath = getConfigPath(cwd, docsDir);
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return configPath;
+}
+
+export function buildReadme(config) {
+  const repoLine = config.repositoryUrl
+    ? `Repository: ${config.repositoryUrl}`
+    : "Repository: (not set — run `npx destinotes-skills` to configure)";
+
+  return `# ${config.projectName}
+
+${config.description ? `${config.description}\n\n` : ""}Generated technical documentation for this project. Agent skills write markdown files in \`./${config.docsDir}/\`.
+
+${repoLine}
+
+## Regenerate
+
+- Whole-repo wiki: \`/destinotes-general\`
+- Single feature: \`/destinotes-feature <slug> <context>\`
+- Custom doc: \`/destinotes-document <folder>:<file> <context>\`
+- Cost analysis: \`/destinotes-cost-analysis <slug> <context>\`
+
+Reconfigure: \`npx destinotes-skills\`
+`;
+}
+
+export function scaffoldDocs(cwd, config, { overwriteReadme = false } = {}) {
+  const docsDir = join(cwd, config.docsDir);
+  const readmePath = join(docsDir, "README.md");
+  mkdirSync(docsDir, { recursive: true });
+
+  const configPath = writeConfig(cwd, config);
+
+  let readmeCreated = false;
+  if (overwriteReadme || !existsSync(readmePath)) {
+    writeFileSync(readmePath, buildReadme(config), "utf8");
+    readmeCreated = true;
+  }
+
+  return { configPath, readmePath, readmeCreated };
+}

package/bin/lib/git.mjs

@@ -0,0 +1,66 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+function runGit(cwd, args) {
+  try {
+    return execSync(`git ${args.join(" ")}`, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRemoteUrl(url) {
+  if (!url) {
+    return null;
+  }
+
+  if (url.startsWith("git@")) {
+    const match = url.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+    if (match) {
+      return `https://${match[1]}/${match[2]}`;
+    }
+  }
+
+  return url.replace(/\.git$/, "");
+}
+
+export function detectGitContext(cwd) {
+  const isRepo = existsSync(join(cwd, ".git"));
+  if (!isRepo) {
+    return {
+      isRepo: false,
+      repositoryUrl: null,
+      defaultBranch: "main",
+    };
+  }
+
+  const remote = runGit(cwd, ["remote", "get-url", "origin"]);
+  const branch = runGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "main";
+
+  return {
+    isRepo: true,
+    repositoryUrl: normalizeRemoteUrl(remote),
+    defaultBranch: branch,
+  };
+}
+
+export function detectProjectName(cwd) {
+  const packageJsonPath = join(cwd, "package.json");
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+      if (pkg.name) {
+        return pkg.name.replace(/^@[^/]+\//, "");
+      }
+    } catch {
+      // ignore invalid package.json
+    }
+  }
+
+  return basename(cwd);
+}

package/bin/lib/prompt.mjs

@@ -0,0 +1,42 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export async function createPrompter() {
+  return createInterface({ input, output });
+}
+
+export async function ask(rl, question, defaultValue = "") {
+  const suffix = defaultValue ? ` (${defaultValue})` : "";
+  const answer = (await rl.question(`${question}${suffix}: `)).trim();
+  return answer || defaultValue;
+}
+
+export async function confirm(rl, question, defaultYes = true) {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  const answer = (await rl.question(`${question} [${hint}]: `)).trim().toLowerCase();
+
+  if (!answer) {
+    return defaultYes;
+  }
+
+  return answer === "y" || answer === "yes";
+}
+
+export async function chooseAgents(rl, detected, labels) {
+  const selected = [];
+
+  console.log("\nWhich coding agents should receive the skills?");
+  for (const id of detected) {
+    const yes = await confirm(rl, `  Install for ${labels[id]}?`, true);
+    if (yes) {
+      selected.push(id);
+    }
+  }
+
+  if (selected.length === 0) {
+    console.log("  No agents selected — defaulting to all detected agents.");
+    return detected;
+  }
+
+  return selected;
+}

package/bin/setup.mjs

@@ -0,0 +1,149 @@
+import { detectGitContext, detectProjectName } from "./lib/git.mjs";
+import {
+  CONFIG_VERSION,
+  readConfig,
+  scaffoldDocs,
+} from "./lib/config.mjs";
+import {
+  ask,
+  chooseAgents,
+  confirm,
+  createPrompter,
+} from "./lib/prompt.mjs";
+
+export async function runSetup({
+  cwd,
+  global = false,
+  yes = false,
+  agents = null,
+  detectedAgents,
+  agentLabels,
+}) {
+  const git = detectGitContext(cwd);
+  const existing = readConfig(cwd);
+
+  if (yes) {
+    return {
+      version: CONFIG_VERSION,
+      projectName: existing?.projectName ?? detectProjectName(cwd),
+      description: existing?.description ?? "",
+      repositoryUrl: existing?.repositoryUrl ?? git.repositoryUrl ?? "",
+      defaultBranch: existing?.defaultBranch ?? git.defaultBranch,
+      docsDir: existing?.docsDir ?? "destinotes",
+      installedAt: new Date().toISOString(),
+      global,
+      agents: agents ?? existing?.agents ?? detectedAgents,
+    };
+  }
+
+  const rl = await createPrompter();
+
+  try {
+    console.log("\nDestinotes setup\n");
+
+    if (existing) {
+      const reconfigure = await confirm(
+        rl,
+        "Existing destinotes.config.json found. Reconfigure project settings?",
+        false,
+      );
+
+      if (!reconfigure) {
+        console.log("Keeping existing project settings.");
+        const selectedAgents =
+          agents ??
+          existing.agents ??
+          (await chooseAgents(rl, detectedAgents, agentLabels));
+
+        return {
+          ...existing,
+          global: existing.global ?? global,
+          agents: selectedAgents,
+        };
+      }
+    }
+
+    const projectName = await ask(
+      rl,
+      "Project name",
+      existing?.projectName ?? detectProjectName(cwd),
+    );
+
+    const repositoryUrl = await ask(
+      rl,
+      "Repository URL",
+      existing?.repositoryUrl ?? git.repositoryUrl ?? "",
+    );
+
+    const defaultBranch = await ask(
+      rl,
+      "Default branch",
+      existing?.defaultBranch ?? git.defaultBranch,
+    );
+
+    const docsDir = await ask(
+      rl,
+      "Docs output folder (relative to project root)",
+      existing?.docsDir ?? "destinotes",
+    );
+
+    const description = await ask(
+      rl,
+      "Short project description (optional)",
+      existing?.description ?? "",
+    );
+
+    if (!global) {
+      global = await confirm(
+        rl,
+        "Install skills globally (all projects) instead of this project only?",
+        false,
+      );
+    }
+
+    const selectedAgents =
+      agents ?? (await chooseAgents(rl, detectedAgents, agentLabels));
+
+    const config = {
+      version: CONFIG_VERSION,
+      projectName,
+      description,
+      repositoryUrl,
+      defaultBranch,
+      docsDir,
+      installedAt: new Date().toISOString(),
+      global,
+      agents: selectedAgents,
+    };
+
+    console.log("\nSetup summary:");
+    console.log(`  Project:     ${config.projectName}`);
+    console.log(`  Repository:  ${config.repositoryUrl || "(none)"}`);
+    console.log(`  Branch:      ${config.defaultBranch}`);
+    console.log(`  Docs folder: ./${config.docsDir}/`);
+    console.log(
+      `  Agents:      ${selectedAgents.map((id) => agentLabels[id]).join(", ")}`,
+    );
+    console.log(`  Scope:       ${global ? "global" : "this project"}`);
+
+    const proceed = await confirm(rl, "\nProceed with install?", true);
+    if (!proceed) {
+      console.log("Setup cancelled.");
+      process.exit(0);
+    }
+
+    return config;
+  } finally {
+    rl.close();
+  }
+}
+
+export function finalizeProjectFiles(cwd, config, existingConfig) {
+  if (config.global) {
+    return null;
+  }
+
+  return scaffoldDocs(cwd, config, {
+    overwriteReadme: Boolean(existingConfig),
+  });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "destinotes-skills",
+  "version": "0.2.0",
+  "description": "Agent skills that generate repository documentation under ./destinotes/",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "destinotes-skills": "./bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "keywords": [
+    "agent-skill",
+    "cursor",
+    "claude-code",
+    "documentation",
+    "destinotes",
+    "wiki"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/destinotes/destinotes.git",
+    "directory": "packages/skills"
+  }
+}

package/skills/destinotes-cost-analysis/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: destinotes-cost-analysis
+description: >-
+  Produces cost-analysis documentation for one feature or system slice by
+  combining repository evidence with live vendor pricing docs. Invoke with
+  /destinotes-cost-analysis [analysis-slug] [context]. Maps billable units
+  (tokens, requests, GB, minutes, seats), applies pricing sources, and writes
+  a pricing report under ./destinotes/cost-analysis/<slug>.md.
+---
+
+# Destinotes Cost Analysis — Money-focused technical doc
+
+**Inherits all rules from `destinotes-prompt`** (output location, folder discovery, document skeleton — *Contents / Tags / Develop the issue* — tone, code citation, freshness footer). Read that skill first; this file only adds cost-scope rules.
+
+---
+
+## Invocation (context required)
+
+```
+/destinotes-cost-analysis [analysis-slug] [context]
+```
+
+| Param | Required | Meaning |
+|---|---|---|
+| `context` | **Yes** | Target capability/workload and what to include (token spend, storage, egress, queue ops, monthly scenarios). |
+| `analysis-slug` | No* | `kebab-case` stem. If omitted, derive from context and echo it under *Contents*. |
+
+## Output path
+
+`./destinotes/cost-analysis/<analysis-slug>.md` — fixed. One primary file per invocation. On update, preserve `<!-- human:begin --> ... <!-- human:end -->` blocks.
+
+## Data collection workflow
+
+1. Parse `context` → scope + workloads + required outputs.
+2. Scan repo for cost drivers: routes, workers, model calls, DB R/W, storage, egress, cron/queues, third-party SDKs, plan limits.
+3. Identify billable units per driver (input/output tokens, requests, GB-month, GB egress, compute minutes, seats/month).
+4. Web-research **official** vendor pricing pages (calculators, quotas, free tier, region notes); record source URL + retrieval date.
+5. Build formulas and run **Low / Base / High** scenarios.
+6. Mark unverifiable prices as `Unknown` and route to *Gaps & follow-ups*.
+
+## Extra required sections (per analysis)
+
+Append these **after** the parent skeleton’s `Develop the issue`:
+
+1. **Scope** — In scope / Out of scope.
+2. **Cost drivers** — Table: `driver | component/file | billable unit | why it costs money`.
+3. **Pricing sources** — Table: `provider | plan/tier | unit price | source URL | retrieved date`.
+4. **Assumptions & formulas** — Explicit assumptions and exact math (e.g. `monthly_cost = requests × price_per_request`).
+5. **Scenario estimates** — At least 3 scenarios (Low / Base / High) with monthly totals and per-unit breakdown.
+6. **Architecture-to-cost diagram** — Mermaid `flowchart LR` showing request path and where each billable event occurs.
+7. **Sensitivity analysis** — Variables that move cost most (token length, cache hit rate, retention, egress).
+8. **Optimization opportunities** — Concrete actions with expected impact and tradeoffs.
+9. **Risks & unknowns** — Missing prices, ambiguous units, rate-limit / plan-change risk.
+10. **Gaps & follow-ups** — What to instrument, contracts to review, dashboards to add.
+
+Add when relevant: **Unit economics** (cost per request/user/document), **Break-even points**, **Regional / currency notes**, **Validation plan** (estimates vs real invoices).
+
+## Baseline table templates
+
+```markdown
+### Cost driver inventory
+| Driver | Source location | Unit | Baseline usage | Notes |
+
+### Scenario estimates
+| Scenario | Requests/mo | Tokens in/out or ops | Storage / Egress | Estimated monthly cost |
+
+### Optimization backlog
+| Opportunity | Estimated savings | Effort | Risk | Owner |
+```
+
+## Quality rules
+
+- Architecture/workload claims cite repo paths and symbols (per `destinotes-prompt`).
+- Pricing claims cite **official** vendor pages; avoid secondary blogs unless no official source exists.
+- Never present uncertain values as fact—mark `Assumption` or `Unknown`.
+
+## Triggers
+
+`/destinotes-cost-analysis`, requests for cost estimate, pricing analysis, unit economics, token spend / LLM cost modeling, infra cost breakdown per request/user/month, or provider pricing comparison grounded in repo workload.

package/skills/destinotes-document/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: destinotes-document
+description: >-
+  Generates one custom markdown document at an arbitrary path under
+  ./destinotes/, chosen by the caller (folder + file). Invoke with
+  /destinotes-document [folderName]:[fileName] [context] for narrative or
+  scoped docs that do not fit destinotes-general (whole-repo) or
+  destinotes-feature (single feature) or destinotes-cost-analysis (pricing).
+---
+
+# Destinotes Document — Custom-path technical note
+
+**Inherits all rules from `destinotes-prompt`** (output location, folder discovery, document skeleton — *Contents / Tags / Develop the issue* — tone, code citation, freshness footer). Read that skill first; this file only adds custom-path rules.
+
+---
+
+## Invocation
+
+```
+/destinotes-document [folderName]:[fileName] [context]
+```
+
+| Param | Required | Meaning |
+|---|---|---|
+| `folderName` | Yes | Subfolder under `./destinotes/` (e.g. `api`, `modules/auth`, `patterns`). Must already exist or be approved by the user (see folder discovery in `destinotes-prompt`). |
+| `fileName` | Yes | Markdown stem without `.md` (kebab-case, e.g. `oauth-flow`). |
+| `context` | Yes | Plain-language description of what to document, scope, and audience. |
+
+If `folderName` does not exist, ask the user before creating it.
+
+## Output path
+
+`./destinotes/<folderName>/<fileName>.md`. Overwrite if the file exists; preserve `<!-- human:begin --> ... <!-- human:end -->` blocks.
+
+## Workflow
+
+1. Parse `context` into subject, scope, audience, exclusions.
+2. List `./destinotes/` to confirm the target folder fits the subject; otherwise ask.
+3. Search the repo for the materials referenced in `context` (modules, routes, schemas, jobs, configs, tests).
+4. Write the doc using the parent skeleton, then add the extra sections below as relevant.
+
+## Extra recommended sections
+
+Pick what fits the subject; omit empty ones. All go after `Develop the issue`.
+
+- **Scope** — In scope / Out of scope.
+- **Architecture** — Components, dependencies, data flow (mermaid when helpful).
+- **Public surface** — Functions/classes/endpoints/events with signatures.
+- **Data & types** — Schemas, DB tables, TS/Zod types.
+- **Configuration** — Env vars, feature flags, config files (names only).
+- **Errors & edge cases** — What can fail and how.
+- **Examples** — Short, real excerpts from the repo (with paths) or minimal usage snippets.
+- **Related docs** — Links to other `./destinotes/...` files.
+- **Gaps & follow-ups** — Open questions, missing coverage.
+
+## Optional metadata flags
+
+The caller may append flags; render them inside `## 2. Tags` or as a small metadata line under the title:
+
+- `--version=X.Y` · `--status=draft|review|published` · `--audience=backend,frontend,devops` · `--tags=tag1,tag2`
+
+## Triggers
+
+`/destinotes-document`, requests for a narrative or scoped doc at an arbitrary `./destinotes/<folder>/<file>.md` path that is **not** a whole-repo wiki, a single feature dive, or a pricing report.

package/skills/destinotes-feature/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: destinotes-feature
+description: >-
+  Documents a single app feature from required natural-language context:
+  locates relevant routes, handlers, jobs, and data paths in the repo and
+  writes one markdown doc under ./destinotes/features/<slug>.md. Use for
+  feature deep dives (JWT creation, OAuth callback, billing webhook)—not
+  whole-repo wikis or arbitrary destinotes paths.
+---
+
+# Destinotes Feature — Single-feature technical note
+
+**Inherits all rules from `destinotes-prompt`** (output location, folder discovery, document skeleton — *Contents / Tags / Develop the issue* — tone, code citation, freshness footer). Read that skill first; this file only adds feature-scope rules.
+
+---
+
+## Invocation (context required)
+
+```
+/destinotes-feature [feature-slug] [context]
+```
+
+| Param | Required | Meaning |
+|---|---|---|
+| `context` | **Yes** | What the feature is, what to include, audience, boundaries. If only one block of text is given, treat it as `context` and derive `feature-slug`. |
+| `feature-slug` | No* | `kebab-case` stem. If omitted, derive from the first explicit feature name in `context` (e.g. “JWT access token creation” → `jwt-access-token-creation`) and echo the chosen slug under *Contents*. |
+
+## Output path
+
+`./destinotes/features/<feature-slug>.md` — fixed. Use only `a-z`, `0-9`, hyphens. If the feature splits (server + client), keep one file with subsections; only add `…-<facet>.md` when the user asks.
+
+## Discovery workflow
+
+1. Parse `context` for scope, inclusions, exclusions, sensitivity.
+2. Search the repo: routes, API handlers, server actions, middleware, `lib/`, workers, config, types, Supabase/migrations, related tests.
+3. Build an **implementation map** (path → role); trim to files that materially participate.
+4. Trace one **primary success path** and note **failure** branches from entry (HTTP/UI/event) to persistence/external IO.
+5. If `./destinotes/features/<feature-slug>.md` exists, update it.
+
+## Extra required sections (per feature doc)
+
+Append these **after** the parent skeleton’s `Develop the issue`:
+
+1. **Scope** — In scope / Out of scope (2–5 bullets each).
+2. **Surface area** — Routes (method + path), UI entry, CLI, queue topic. Table preferred.
+3. **Implementation map** — Table: `path | responsibility | key symbols`.
+4. **Control flow** — Mermaid `sequenceDiagram` or `flowchart LR` for the main path (≤ ~15 nodes).
+5. **Data & types** — Payloads, DB tables/columns touched, TS types or Zod schemas.
+6. **Security & trust** — Authn/z, secrets (names only), CSRF/cookies, validation, multi-tenant boundaries. `N/A` line if irrelevant.
+7. **Errors & edge cases** — Status codes, retries, idempotency, race conditions evidenced in code.
+8. **Configuration** — Env vars and config files by name; default vs production differences if visible.
+9. **Verification** — Manual test steps or test files/commands (`npm run test …`, file:line pointers).
+10. **Gaps & follow-ups** — Unknowns, suspected dead code, missing tests. Do not invent answers.
+
+Add when useful: **Dependencies** (internal modules; link to `../libraries/inventory.md`), **Performance** (only if evidenced), **Related docs**.
+
+## Triggers
+
+`/destinotes-feature`, “document this feature” targeting `features/`, or a request for a route-level explanation of one capability (JWT, OAuth, webhooks, billing, etc.) as a single Destinotes file.

package/skills/destinotes-general/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: destinotes-general
+description: >-
+  Bootstraps or refreshes a full-repository technical wiki under ./destinotes/
+  by scanning the codebase and writing one seed article per fixed category
+  (architecture, libraries, security, deployment, data, configuration,
+  integrations, testing, development, observability). Use for whole-repo docs
+  baselines and onboarding packs—not for single-feature docs.
+---
+
+# Destinotes General — Repository wiki bootstrap
+
+**Inherits all rules from `destinotes-prompt`** (output location, folder discovery, document skeleton — *Contents / Tags / Develop the issue* — tone, code citation, freshness footer). Read that skill first; this file only adds whole-repo scope.
+
+---
+
+## Invocation
+
+```
+/destinotes-general [optional context]
+```
+
+Optional context: target audience (new hire, security review), emphasis (“focus on auth”), or partial refresh (“refresh only libraries + deployment”).
+
+## Output
+
+One seed article per category under `./destinotes/`. Create folders if missing; update files in place if present.
+
+| Folder | Seed file | Purpose |
+|---|---|---|
+| `architecture/` | `overview.md` | System shape, components, data/control flow, boundaries |
+| `libraries/` | `inventory.md` | Deps + devDeps with **resolved versions** (lockfile preferred; otherwise quote `package.json` ranges and flag) |
+| `security/` | `posture.md` | Authn/z, secrets, headers, supply chain, hardening |
+| `deployment/` | `pipeline-and-hosting.md` | Build, hosting, env vars, migrations, rollback |
+| `data-and-storage/` | `overview.md` | DB, R2/KV/D1, Supabase schema, retention |
+| `configuration/` | `environment.md` | Env files, `wrangler.toml`, flags, per-env deltas |
+| `integrations/` | `external-services.md` | OAuth, email, analytics, webhooks, rate limits |
+| `testing-and-quality/` | `gates.md` | Test runners, coverage, lint/typecheck gates |
+| `development/` | `local-setup.md` | Setup, scripts, conventions, troubleshooting |
+| `observability/` | `overview.md` | Logging, metrics, tracing, error reporting |
+
+Add `compliance-and-privacy/`, `performance/`, or `user-guide/` only when the repo has meaningful content for them. Also create `./destinotes/README.md` (one paragraph: layout + how to regenerate).
+
+## Extra required sections (per article)
+
+Append these **after** the parent skeleton’s `Develop the issue`:
+
+1. **Facts from the repository** — Tables of paths, versions, bindings. No speculation.
+2. **Diagrams** — Mermaid (flowchart/LR for pipelines, sequenceDiagram for auth/email). Keep small.
+3. **Key files & entry points** — Bulleted repo-relative paths.
+4. **Gaps & follow-ups** — Unknowns, TODOs, files not yet read.
+
+Add when relevant: **Scope & out of scope**, **Decisions & constraints** (ADR-style one-liners inferred from config/code), **Operational notes**, **References**.
+
+## Execution checklist
+
+1. Map repo: package manager, framework, infra files (`wrangler.toml`, Docker, `.github/workflows`).
+2. Read lockfile + `package.json` → `libraries/inventory.md`.
+3. Read deployment + README/scripts → `deployment/` + `configuration/`.
+4. Skim auth, middleware, routes, server actions → `security/` + `architecture/`.
+5. Skim Supabase/migrations/ORM → `data-and-storage/`.
+6. Write/update all seed articles in one pass; keep cross-links consistent.
+
+## Triggers
+
+`/destinotes-general`, “whole repo overview”, “wiki bootstrap”, “onboarding docs pack”, “refresh destinotes tree”, or any request for a project-wide architecture + libraries + security snapshot.

package/skills/destinotes-prompt/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: destinotes-prompt
+description: >-
+  Parent skill and shared contract for every destinotes-* skill. Defines the
+  output location, folder/subject conventions, document skeleton (Contents,
+  Tags, Develop the issue), code-citation rules, and tone. All other
+  destinotes-* skills MUST read this file first and inherit its rules; they
+  only add their own scope and skill-specific sections on top.
+---
+
+# Destinotes Prompt — Shared contract for all destinotes-* skills
+
+This is the **parent** skill. Every other `destinotes-*` skill (`destinotes-general`, `destinotes-feature`, `destinotes-document`, `destinotes-cost-analysis`, …) **must read this file first** and obey the rules below. Child skills only add **scope, invocation, and extra sections**—they do not override these defaults.
+
+---
+
+## 1. Output is always markdown under `./destinotes/`
+
+- Every artifact is a single `.md` file.
+- Root for all docs: `./destinotes/` (repo-relative), unless `destinotes/destinotes.config.json` sets a different `docsDir` — then use `./<docsDir>/` instead.
+- Each **subfolder = one subject** (e.g. `architecture/`, `security/`, `features/`, `cost-analysis/`).
+- **Never** write outside the configured docs root and never create binaries.
+
+### Project config (read first)
+
+If `destinotes/destinotes.config.json` exists (or `<docsDir>/destinotes.config.json`), read it before writing docs. Use:
+
+- `projectName` — human title in generated READMEs and doc intros when relevant
+- `repositoryUrl` — link back to the canonical repo in cross-references
+- `defaultBranch` — when citing branches or comparing to main
+- `description` — one-line project context where helpful
+- `docsDir` — output root (default `destinotes`)
+
+Do not invent values missing from config; omit or mark as unknown.
+
+## 2. Folder discovery before writing
+
+Before creating any file:
+
+1. List `./destinotes/` and inspect existing subfolders.
+2. Pick the folder whose **subject** best fits the new doc.
+3. If no folder fits, **ask the user** whether to create a new folder (propose a kebab-case name); do not invent folders silently.
+4. Child skills with a fixed output path (e.g. `features/`, `cost-analysis/`) keep that path; only ambiguous docs trigger the question.
+
+## 3. Required document skeleton
+
+Every generated doc starts with these three sections in this order:
+
+```markdown
+# <Human Title>
+
+## 1. Contents
+
+- One short bullet per section in this doc, describing what it covers.
+
+## 2. Tags
+
+`tag-one` `tag-two` `tag-three`
+
+## 3. Develop the issue
+
+<Main body. Expand the subject as broadly as possible while staying concise.
+Cover what it is, how it works in this repo, key flows, edge cases, and
+boundaries. Use tables and mermaid diagrams over prose when they compress
+information.>
+```
+
+- **Contents** = a description of what the document contains (not a clickable TOC).
+- **Tags** = 3–8 short kebab-case tags that aid search/grouping in Destinotes.
+- **Develop the issue** = the substantive body. Child skills add their own subsections here (and may add sibling top-level sections after it).
+- Child skills append their **extra required sections** after `Develop the issue` (e.g. *Cost drivers*, *Implementation map*, *Pricing sources*).
+
+## 4. Tone & coverage
+
+- **Concise, direct, complete.** No filler, no marketing language, no restating the question.
+- **Broad but tight**: cover the whole subject; cut anything not load-bearing.
+- Prefer **tables**, **bulleted lists**, and **mermaid** over long paragraphs.
+- Never invent behavior, versions, or APIs not evidenced in the repo or in cited sources.
+- If unknown, list it under a final **Gaps & follow-ups** bullet—do not guess.
+
+## 5. Grounding in the actual codebase
+
+- Use **real code from this repository** as evidence.
+- Every code excerpt must include the **repo-relative path** and ideally the line range and symbol name.
+- Use this exact citation format for existing code:
+
+```startLine:endLine:repo/relative/path
+// short, faithful excerpt
+```
+
+- Prefer short excerpts (≤ ~15 lines). For longer logic, cite path + symbol and summarize.
+- **Never** paste secret values; reference variable names only and point to `.env.example`, `wrangler secret put`, etc.
+
+## 6. Cross-linking & freshness
+
+- Link related Destinotes docs with relative paths (e.g. `../architecture/overview.md`).
+- End every doc with a one-line footer: `Last updated: YYYY-MM-DD` (use today’s date if available in session).
+- When updating an existing file, preserve any block wrapped in `<!-- human:begin --> ... <!-- human:end -->` exactly.
+
+---
+
+## How child skills extend this
+
+A child skill’s `SKILL.md` should:
+
+1. Reference this file in its preamble (“inherits rules from `destinotes-prompt`”).
+2. Define its **invocation**, **fixed output path** (or rule for choosing one), and **scope**.
+3. List the **extra required sections** to append after `Develop the issue`.
+4. Avoid re-stating tone, length, citation, or folder rules—they live here.
+
+Children currently bound to this contract:
+
+| Skill | Scope | Output path |
+|-------|-------|-------------|
+| `destinotes-general` | Whole-repo wiki bootstrap | `./destinotes/<category>/*.md` |
+| `destinotes-feature` | Single feature deep dive | `./destinotes/features/<slug>.md` |
+| `destinotes-document` | Custom `folder:file` doc | `./destinotes/<folder>/<file>.md` |
+| `destinotes-cost-analysis` | Pricing/cost report | `./destinotes/cost-analysis/<slug>.md` |
+
+---
+
+## Triggers
+
+This skill is **always implicitly active** whenever a `destinotes-*` skill runs. Read it before producing any Destinotes file.