incitaciones 0.3.0 → 0.3.2

package/pi-package/skills/review-documentation/references/ai-readiness-criteria.md

@@ -0,0 +1,38 @@
+# AI-Readiness Criteria (Pass 5)
+
+Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer First) catches surface issues; these checks catch whether the page is actually consumable by an AI agent. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability").
+
+## LLM-friendly structure
+
+- Is there a concise TL;DR (1-2 sentences) at the top suitable for context-window injection?
+- Is the page free of navigation chrome when exported (menus, footers, ads) so the body text is clean?
+- Is prose minimalist and high-signal? Verbose docs cost more and retrieve worse.
+
+## RAG-compatible chunking
+
+- Does the page cover one well-defined topic so it chunks cleanly for retrieval?
+- Are section headings stable and unique so a chunk can be addressed precisely?
+- Is there redundant cross-page duplication that would pollute retrieval results?
+
+## Semantic headers
+
+- Are headers descriptive of content, not generic ("Overview", "Details")?
+- Are headers unique across the site so a model can disambiguate?
+- Is front matter present (title, description, version, category) for indexing?
+
+## Dual-audience precision
+
+- Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent.
+- Are error conditions and their meanings explicit?
+- Are capability boundaries stated (what the tool/API can and cannot do)?
+
+## Schema and spec sync (reference pages)
+
+- For API reference: is it generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)?
+- For tool/agent docs: are MCP manifests and agent cards present with precise descriptions and JSON schemas for inputs/outputs?
+- Are code examples complete and runnable? Agents execute what they read; partial snippets mislead.
+
+## Site-level (flag only if the page is the canonical entry)
+
+- Is a `llms.txt` present at the documentation root and does it reference this page where authoritative?
+- Are canonical URLs set so a model retrieves the current stable version?

package/scripts/generate-pi-resources.mjs

@@ -2,6 +2,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import process from "node:process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,6 +34,15 @@ function readText(filePath) {
   return fs.readFileSync(filePath, "utf8");
 }
 
+function getPackageVersion() {
+  try {
+    const pkg = JSON.parse(readText(path.join(repoRoot, "package.json")));
+    return `npm:${pkg.version}`;
+  } catch {
+    return new Date().toISOString().slice(0, 10);
+  }
+}
+
 function generateSkill(prompt) {
   const distilledPath = path.join(repoRoot, prompt.distilled);
   const skillDir = path.join(skillsOut, prompt.name);
@@ -83,6 +94,113 @@ function generatePromptTemplate(prompt) {
   fs.writeFileSync(path.join(promptsOut, `${prompt.name}.md`), template, "utf8");
 }
 
+/**
+ * Detect flat-skills directories that already have incitaciones skills installed,
+ * and re-sync them with the latest pi-package content. This ensures that
+ * pi update / npm version bumps keep flat-install locations current.
+ *
+ * Flat installs (e.g. ~/.agents/skills/) are created by install.sh and
+ * npx incitaciones install, but are NOT managed by pi's package reader
+ * (which reads directly from pi-package/skills/). Without this re-sync,
+ * a version bump leaves those directories stale.
+ */
+function reSyncFlatInstallSkills(manifest) {
+  const version = getPackageVersion();
+  const now = new Date().toISOString().replace("Z", "000Z");
+  const home = homedir();
+
+  // Candidate directories to check for incitaciones flat installs
+  const candidates = [
+    path.join(home, ".agents", "skills"),
+    path.join(home, ".config", "agents", "skills"),
+  ];
+
+  // Also check .agents/skills in cwd for project-local installs
+  try {
+    candidates.push(path.join(process.cwd(), ".agents", "skills"));
+  } catch {}
+
+  // Deduplicate
+  const checked = new Set();
+  const dirs = candidates.filter((d) => {
+    if (checked.has(d)) return false;
+    checked.add(d);
+    return fs.existsSync(d);
+  });
+
+  let synced = 0;
+  for (const dir of dirs) {
+    // Check if this directory has incitaciones-installed skills
+    // by reading the first SKILL.md we find and checking its frontmatter
+    let hasIncitaciones = false;
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const skillFile = path.join(dir, entry.name, "SKILL.md");
+        if (!fs.existsSync(skillFile)) continue;
+        const content = fs.readFileSync(skillFile, "utf8");
+        if (content.includes("installed-from: incitaciones") || content.includes("installed-from: \"incitaciones\"")) {
+          hasIncitaciones = true;
+          break;
+        }
+      }
+    } catch {
+      // Permission issues, etc. — skip
+      continue;
+    }
+
+    if (!hasIncitaciones) continue;
+
+    // Re-sync: for each prompt in manifest, copy from pi-package/skills/ to flat dir
+    for (const prompt of manifest.prompts) {
+      const srcDir = path.join(skillsOut, prompt.name);
+      if (!fs.existsSync(srcDir)) continue;
+
+      const dstDir = path.join(dir, prompt.name);
+      fs.rmSync(dstDir, { recursive: true, force: true });
+      fs.mkdirSync(dstDir, { recursive: true });
+
+      // Generate flat-format frontmatter for SKILL.md
+      const distilledPath = path.join(repoRoot, prompt.distilled);
+      if (!fs.existsSync(distilledPath)) continue;
+
+      const description = escapeYamlDoubleQuoted(prompt.description || `Incitaciones prompt: ${prompt.name}`);
+      const frontmatter = [
+        "---",
+        `name: ${prompt.name}`,
+        `description: "${description}"`,
+        "installed-from: incitaciones",
+        `installed-version: "${version}"`,
+        `installed-at: "${now}"`,
+        "---",
+        "",
+      ].join("\n");
+
+      fs.writeFileSync(path.join(dstDir, "SKILL.md"), frontmatter + readText(distilledPath), "utf8");
+
+      // Copy references/ from the source skill directory
+      if (distilledPath.endsWith(`${path.sep}SKILL.md`)) {
+        const srcRefDir = path.dirname(distilledPath);
+        for (const entry of fs.readdirSync(srcRefDir, { withFileTypes: true })) {
+          if (entry.name === "SKILL.md") continue;
+          const s = path.join(srcRefDir, entry.name);
+          const d = path.join(dstDir, entry.name);
+          if (entry.isDirectory()) {
+            fs.cpSync(s, d, { recursive: true });
+          } else {
+            fs.copyFileSync(s, d);
+          }
+        }
+      }
+    }
+    synced++;
+  }
+
+  if (synced > 0) {
+    console.log(`Re-synced incitaciones skills in ${synced} flat-install director(ies)`);
+  }
+}
+
 function main() {
   const manifest = JSON.parse(readText(manifestPath));
   resetDir(outRoot);
@@ -117,6 +235,9 @@ function main() {
   fs.writeFileSync(path.join(outRoot, "README.md"), readme, "utf8");
 
   console.log(`Generated pi resources for ${manifest.prompts.length} prompts in ${path.relative(repoRoot, outRoot)}/`);
+
+  // Re-sync any existing flat-install skill directories (e.g. ~/.agents/skills/)
+  reSyncFlatInstallSkills(manifest);
 }
 
-main();
+main();

package/content/distilled/implement-documentation.md

@@ -1,68 +0,0 @@
-# Implement Documentation Topic
-
-Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.
-
-## CRITICAL RULES
-
-1. ✅ **DO:** Establish context and prerequisites in the first two sentences (EPPO).
-2. ✅ **DO:** Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
-3. ✅ **DO:** Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
-4. ✅ **DO:** Provide a clear "fail-state" or troubleshooting section (Minimalism).
-5. ❌ **DO NOT:** Mix intents (e.g., no deep theory in a How-to guide). If theory is *required* for a task, use a **Note:** or **Deep Dive:** sidebar to maintain quadrant purity.
-6. ❌ **DO NOT:** Use "Next" or "Previous" as the only navigational cues (EPPO).
-
-## Implementation Workflow
-
-### Step 1: Quadrant Check
-
-Identify the Diátaxis quadrant and follow its rhetorical rules:
-- **Tutorial:** Action-oriented, safe environment. Use the **Martini Glass** narrative pattern: Author-driven stem (guided context) → Reader-driven bowl (open exploration).
-- **How-to:** Task-focused, assumes baseline competence, minimal theory.
-- **Reference:** Fact-based, scannable tables, no narrative filler.
-- **Explanation:** Theoretical, discusses "Why," maps concepts.
-
-### Step 2: EPPO Initialization
-
-Every topic must stand alone. Start with:
-- **Title:** Clear, task- or concept-focused.
-- **Context Block:** "This topic covers [X]. You should already understand [Y] and have [Z] installed."
-
-### Step 3: Information Mapping
-
-Structure the body content:
-- **Chunking:** Break large blocks into units of <7 items.
-- **Labeling:** Use headers that describe the *result* or *content* (e.g., "Configuring the API" not just "Configuration").
-- **Tables/Lists:** Convert complex comparisons or steps into visual structures.
-
-### Step 4: AI-First Polish
-
-- **Semantic Headers:** Ensure headers are descriptive for RAG indexing.
-- **Compressed Summary:** Provide a 1-2 sentence "tl;dr" at the top for LLM ingestion.
-
-## Template (How-to Guide)
-
-```markdown
-# [Task-Focused Title]
-
-**TL;DR:** [1-sentence summary for human/AI]
-
-## Context & Prerequisites
-This guide explains how to [Goal]. Before starting, ensure you have:
-- [Prerequisite 1]
-- [Prerequisite 2]
-
-## [Action Step 1: Specific Result]
-[Chunked instructions]
-
-## [Action Step 2: Specific Result]
-[Chunked instructions]
-
-## Troubleshooting: Common Fail-States
-| Symptom | Cause | Fix |
-| :--- | :--- | :--- |
-| [Error] | [Reason] | [Solution] |
-
-## Further Exploration
-- [Lateral Link 1] (Subject affinity)
-- [Lateral Link 2] (Subject affinity)
-```

package/content/distilled/research-documentation.md

@@ -1,79 +0,0 @@
-# Research Documentation Architecture
-
-Audit the existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
-
-## CRITICAL RULES
-
-1. ✅ **DO:** Categorize every document into exactly one Diátaxis quadrant.
-2. ✅ **DO:** Identify "Frankenbooks" (documents with mixed intent/quadrants).
-3. ✅ **DO:** Map the "Snowflake" progression from Core Assertion to granular topics.
-4. ✅ **DO:** Verify EPPO compliance (Does each page establish its own context?).
-5. ❌ **DO NOT:** Start writing content yet; focus on architecture and gaps.
-6. ❌ **DO NOT:** Suggest stylistic changes (focus on structural integrity).
-
-## Process
-
-### Step 1: Define the Scope
-
-[User will provide a path to a documentation directory or a project description.]
-- Identify the primary audience (Novice vs. Expert).
-- State the "Core Assertion" (The single-sentence value proposition).
-- **Legacy Conflict Resolution:** If existing documentation contains multiple, conflicting "hooks," identify the most impactful one or propose a synthesis for the new architecture.
-
-### Step 2: Audit Existing Content (if applicable)
-
-For each file in the directory, determine:
-- **Quadrant:** (Tutorial | How-to | Reference | Explanation).
-- **EPPO Status:** (Pass/Fail) Does it have standalone utility and context?
-- **Cognitive Load:** Are there "walls of words" or missing labels?
-
-### Step 3: Map the Snowflake Outline
-
-Expand the Core Assertion into a structural map:
-1. **Core Assertion:** [1 sentence]
-2. **Macro-Expansion:** [1 paragraph user journey]
-3. **Component List:** [The "characters" of the system]
-4. **Topic Matrix:** A list of proposed EPPO topics categorized by quadrant.
-
-### Step 4: Identify Gaps and Friction
-
-- **Quadrant Imbalance:** e.g., "Too much reference, not enough tutorials."
-- **Structural Plot-holes:** Where does the user journey break?
-- **AI-Readiness Gaps:** Missing `llms.txt`, poor semantic labeling.
-
-### Step 5: Final Research Report
-
-Output the audit/plan using the following template:
-
-```markdown
-# Documentation Research: [Project Name]
-
-## 1. Executive Summary & Core Assertion
-**Core Assertion:** [The one-sentence hook]
-**Status:** [Summary of current architecture health]
-
-## 2. Diátaxis Matrix
-| Quadrant | Existing Topics | Proposed/Missing Topics |
-| :--- | :--- | :--- |
-| **Tutorial** | | |
-| **How-to** | | |
-| **Reference** | | |
-| **Explanation** | | |
-
-## 3. Snowflake Structural Map
-- **Macro-Journey:** [Description]
-- **Key Components:** [List]
-
-## 4. EPPO & Cognitive Audit
-- **Frankenbooks Found:** [List of files with mixed intent]
-- **Context Gaps:** [Topics needing better orientation]
-
-## 5. AI-Readiness Assessment
-- [ ] `llms.txt` present?
-- [ ] Explicit semantic labeling for RAG?
-- [ ] MCP endpoints identified?
-
-## 6. Recommended Next Steps
-1. [Actionable structural change]
-2. [Actionable topic creation]
-```

package/content/distilled/review-documentation.md

@@ -1,44 +0,0 @@
-# Review Documentation Quality
-
-Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture.
-
-## REVIEW PROCESS
-
-Perform 5 iterative passes, checking for convergence after each pass (starting with pass 2).
-
-### PASS 1: Diátaxis & Intent
-- **Goal:** Does this topic have a single, clear intent?
-- **Checks:** Is it a Tutorial, How-to, Reference, or Explanation? Are there "leaked" intents? (e.g., too much theory in a Tutorial).
-- **Issue Prefix:** [INTENT-001]
-
-### PASS 2: EPPO & Standalone Utility
-- **Goal:** Can a "foraging" reader land here and succeed?
-- **Checks:** Are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links?
-- **Issue Prefix:** [EPPO-001]
-
-### PASS 3: Cognitive Scannability (Info Mapping)
-- **Goal:** Can the reader scan the page in <10 seconds and find the key answer?
-- **Checks:** Are **labels** (descriptive headers) used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are there tables/lists for complex data?
-- **Issue Prefix:** [SCAN-001]
-
-### PASS 4: Accuracy, "Whole Game" & Fail-States
-- **Goal:** Is the content technically sound and resilient?
-- **Checks:** Are the code snippets/math verified? Does it show the "Whole Game" (complete result)? Are common errors (fail-states) documented? In tutorials, is the **Martini Glass** pattern followed (context → exploration)?
-- **Issue Prefix:** [ACC-001]
-
-### PASS 5: Excellence & AI-Readiness
-- **Goal:** Is it production-ready and optimized for AI agents?
-- **Checks:** Is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the **Answer First** (Pyramid Principle) located in the TL;DR and first paragraph?
-- **Issue Prefix:** [EXCL-001]
-
-## Convergence Check
-After each pass (starting with pass 2), report:
-- Total new issues found.
-- Estimated "Signal-to-Noise" ratio.
-- Convergence status: (CONVERGED | CONTINUE).
-
-## Final Report Format
-- **Total Issues by Severity** (Critical | High | Medium | Low).
-- **Top 3 Findings.**
-- **Verdict:** (Ready | Needs Revision | Needs Rework).
-- **Rationale.**