@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/discover-cloud/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: discover-cloud
+description: Automatically discover cloud computing and serverless skills when working with cloud. Activates for cloud development tasks.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [cloud-setup, aws-setup, serverless-setup, cloud-provider, gcp-setup]
+---
+
+# Cloud Skills Discovery
+
+Provides automatic access to comprehensive cloud skills.
+
+## When This Skill Activates
+
+This skill auto-activates when you're working with:
+
+- cloud
+- Modal
+- serverless
+- functions
+- AWS
+- GCP
+- Azure
+- deployment
+
+## Available Skills
+
+### Quick Reference
+
+The Cloud category contains 13 skills:
+
+**AWS Skills (7)**:
+
+1. **aws-lambda-functions** - Lambda function development, triggers, optimization
+2. **aws-api-gateway** - REST/HTTP/WebSocket APIs, authorization, integrations
+3. **aws-databases** - RDS, DynamoDB, ElastiCache, Aurora
+4. **aws-iam-security** - IAM, Cognito, Secrets Manager, KMS
+5. **aws-storage** - S3, EBS, EFS, Glacier, lifecycle policies
+6. **aws-ec2-compute** - EC2, Auto Scaling, Load Balancing, AMIs
+7. **aws-networking** - VPC, security groups, Route53, CloudFront
+
+**GCP Skills (6)**:
+
+1. **gcp-serverless** - Cloud Functions, Cloud Run, App Engine
+2. **gcp-compute** - Compute Engine, GKE, autoscaling
+3. **gcp-databases** - Cloud SQL, Firestore, Bigtable, Spanner
+4. **gcp-storage** - Cloud Storage, Persistent Disk, Filestore
+5. **gcp-iam-security** - IAM, service accounts, Secret Manager, KMS
+6. **gcp-networking** - VPC, firewall, Cloud DNS, Cloud CDN
+
+### Load Full Category Details
+
+For complete descriptions and workflows:
+
+```bash
+cat ~/.claude/skills/cloud/INDEX.md
+```
+
+This loads the full Cloud category index with:
+
+- Detailed skill descriptions
+- Usage triggers for each skill
+- Common workflow combinations
+- Cross-references to related skills
+
+### Load Specific Skills
+
+Load individual skills as needed:
+
+```bash
+# AWS Skills
+cat ~/.claude/skills/cloud/aws/aws-lambda-functions.md
+cat ~/.claude/skills/cloud/aws/aws-api-gateway.md
+cat ~/.claude/skills/cloud/aws/aws-databases.md
+cat ~/.claude/skills/cloud/aws/aws-iam-security.md
+cat ~/.claude/skills/cloud/aws/aws-storage.md
+cat ~/.claude/skills/cloud/aws/aws-ec2-compute.md
+cat ~/.claude/skills/cloud/aws/aws-networking.md
+
+# GCP Skills
+cat ~/.claude/skills/cloud/gcp/gcp-serverless.md
+cat ~/.claude/skills/cloud/gcp/gcp-compute.md
+cat ~/.claude/skills/cloud/gcp/gcp-databases.md
+cat ~/.claude/skills/cloud/gcp/gcp-storage.md
+cat ~/.claude/skills/cloud/gcp/gcp-iam-security.md
+cat ~/.claude/skills/cloud/gcp/gcp-networking.md
+```
+
+## Progressive Loading
+
+This gateway skill enables progressive loading:
+
+- **Level 1**: Gateway loads automatically (you're here now)
+- **Level 2**: Load category INDEX.md for full overview
+- **Level 3**: Load specific skills as needed
+
+## Usage Instructions
+
+1. **Auto-activation**: This skill loads automatically when Claude Code detects cloud work
+2. **Browse skills**: Run `cat ~/.claude/skills/cloud/INDEX.md` for full category overview
+3. **Load specific skills**: Use bash commands above to load individual skills
+
+---
+
+**Next Steps**: Run `cat ~/.claude/skills/cloud/INDEX.md` to see full category details.

package/.merlin-core/skills/general/doc-sync/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: doc-sync
+description: Auto-detect stale documentation and suggest updates after code changes
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [sync-docs, stale-docs, update-docs, readme-sync, changelog-update]
+---
+
+# Doc Sync
+
+Automatically detects when code changes may have made documentation outdated and suggests updates. Ensures documentation stays aligned with the codebase.
+
+## How It Works
+
+1. **Code-to-Doc Mapping** — Maps code directories to documentation files and sections:
+   - `core/execution/` → CLAUDE.md "Architecture Overview"
+   - `core/orchestration/` → CLAUDE.md "Slash Commands", "Development Workflows"
+   - `development/agents/` → CLAUDE.md "Agent Roster"
+   - `skills/` → CLAUDE.md "Architecture Overview"
+   - `commands/` → CLAUDE.md "Slash Commands"
+   - `core/alkimia/` → CLAUDE.md "Alkimia Context Engine"
+   - `core/approval/` → CLAUDE.md "Approval System"
+
+2. **Change Detection** — When files are modified, the engine checks if they fall under any mapped code path
+
+3. **Suggestion Generation** — For each affected mapping, generates a suggestion identifying the stale section and reason
+
+## CLI Commands
+
+```bash
+# Check current git diff for stale docs
+node .merlin-core/tools/merlin-tools.js doc-sync check
+
+# View pending suggestions
+node .merlin-core/tools/merlin-tools.js doc-sync suggestions
+
+# Clear suggestions
+node .merlin-core/tools/merlin-tools.js doc-sync clear
+```
+
+## PostToolUse Hook
+
+The `doc-sync.js` hook runs after Write and Edit tool calls, checking if the modified file triggers any documentation staleness. Suggestions are written to `.merlin/doc-sync-suggestions.json`.
+
+## When It Triggers
+
+- After code changes via Write or Edit tools
+- When running `doc-sync check` CLI command manually
+- Does NOT auto-update docs — only suggests what needs review

package/.merlin-core/skills/general/document-sharding/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: document-sharding
+description: Bracket-aware document sharding with progressive load strategies
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [document-sharding, context-budget, progressive-load, large-document]
+---
+
+# Document Sharding
+
+Breaks large documents into chunks and loads them using bracket-aware strategies. Prevents context overflow by loading only what fits the current token budget.
+
+## Load Strategies
+
+### FULL
+
+Returns the entire document within token budget. Used when context is fresh and budget is ample.
+
+### SUMMARY
+
+Returns only the first section (title + introduction). Used in CRITICAL bracket when context is nearly exhausted.
+
+### PROGRESSIVE
+
+Returns the first N sections, loading more on demand. Used in DEPLETED bracket for controlled expansion.
+
+### RELEVANT
+
+Keyword-matches sections and returns only matching chunks, ordered by relevance score. Used in MODERATE bracket for targeted retrieval.
+
+## Bracket Behavior
+
+| Bracket  | Strategy            | Rationale                            |
+| -------- | ------------------- | ------------------------------------ |
+| FRESH    | FULL                | Plenty of context budget             |
+| MODERATE | RELEVANT            | Targeted retrieval to conserve space |
+| DEPLETED | SUMMARY             | Minimal footprint, key info only     |
+| CRITICAL | SUMMARY (truncated) | Absolute minimum for orientation     |
+
+## How It Works
+
+1. Document is split by markdown section headers (`#`, `##`, `###`)
+2. Oversized sections are further split by paragraph boundaries
+3. Each chunk carries metadata: content, index, token count, section name
+4. Load strategy selects which chunks to include based on bracket and keywords
+5. Total never exceeds the remaining token budget
+
+## Integration
+
+The DocumentSharder integrates with ThoughtsProvider to shard large thought documents before injection into the Alkimia context pipeline.

package/.merlin-core/skills/general/docx/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: docx
+description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of Word doc, .docx, or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting content from .docx files, inserting or replacing images, performing find-and-replace, working with tracked changes or comments, or converting content into a polished Word document."
+license: MIT (Anthropic)
+compatibility: claude-code
+metadata:
+  source: anthropic/skills
+  imported: 2026-03-15
+  version: "3.0.0"
+  windows-setup: See references/windows-setup.md for Windows dependency installation
+  auto_activate: [docx, word-doc, word-document, word-file]
+  file_triggers: [*.docx]
+---
+
+# DOCX Creation, Editing, and Analysis
+
+## Overview
+
+A .docx file is a ZIP archive containing XML files.
+
+## Quick Reference
+
+| Task                   | Approach                                                                     |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| Read/analyze content   | `pandoc` or unpack for raw XML                                               |
+| Create new document    | Use docx-js (`npm install -g docx`)                                          |
+| Edit existing document | Unpack → edit XML → repack                                                   |
+| Convert .doc to .docx  | `python scripts/office/soffice.py --headless --convert-to docx document.doc` |
+| Accept tracked changes | `python scripts/accept_changes.py input.docx output.docx`                    |
+| Add comments           | `python scripts/comment.py unpacked/ 0 "Comment text"`                       |
+
+### Reading Content
+
+```bash
+# Text extraction with tracked changes
+pandoc --track-changes=all document.docx -o output.md
+
+# Raw XML access
+python scripts/office/unpack.py document.docx unpacked/
+```
+
+### Converting to Images
+
+```bash
+python scripts/office/soffice.py --headless --convert-to pdf document.docx
+pdftoppm -jpeg -r 150 document.pdf page
+```
+
+---
+
+## Creating New Documents
+
+Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`
+
+### Setup
+
+```javascript
+const {
+  Document,
+  Packer,
+  Paragraph,
+  TextRun,
+  Table,
+  TableRow,
+  TableCell,
+  ImageRun,
+  Header,
+  Footer,
+  AlignmentType,
+  PageOrientation,
+  LevelFormat,
+  ExternalHyperlink,
+  InternalHyperlink,
+  Bookmark,
+  FootnoteReferenceRun,
+  PositionalTab,
+  PositionalTabAlignment,
+  PositionalTabRelativeTo,
+  PositionalTabLeader,
+  TabStopType,
+  TabStopPosition,
+  Column,
+  SectionType,
+  TableOfContents,
+  HeadingLevel,
+  BorderStyle,
+  WidthType,
+  ShadingType,
+  VerticalAlign,
+  PageNumber,
+  PageBreak,
+} = require("docx");
+
+const doc = new Document({
+  sections: [
+    {
+      children: [
+        /* content */
+      ],
+    },
+  ],
+});
+Packer.toBuffer(doc).then((buffer) => fs.writeFileSync("doc.docx", buffer));
+```
+
+### Validation
+
+After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
+
+```bash
+python scripts/office/validate.py doc.docx
+```
+
+### Page Size
+
+```javascript
+// CRITICAL: docx-js defaults to A4, not US Letter
+sections: [
+  {
+    properties: {
+      page: {
+        size: { width: 12240, height: 15840 }, // US Letter in DXA
+        margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 1 inch
+      },
+    },
+    children: [
+      /* content */
+    ],
+  },
+];
+```
+
+| Paper        | Width (DXA) | Height (DXA) | Content Width (1" margins) |
+| ------------ | ----------- | ------------ | -------------------------- |
+| US Letter    | 12,240      | 15,840       | 9,360                      |
+| A4 (default) | 11,906      | 16,838       | 9,026                      |
+
+**Landscape:** Pass portrait dimensions — docx-js swaps internally:
+
+```javascript
+size: { width: 12240, height: 15840, orientation: PageOrientation.LANDSCAPE }
+```
+
+### Styles
+
+Use Arial as the default font. Keep titles black for readability.
+
+```javascript
+const doc = new Document({
+  styles: {
+    default: { document: { run: { font: "Arial", size: 24 } } },
+    paragraphStyles: [
+      {
+        id: "Heading1",
+        name: "Heading 1",
+        basedOn: "Normal",
+        next: "Normal",
+        quickFormat: true,
+        run: { size: 32, bold: true, font: "Arial" },
+        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 },
+      },
+      {
+        id: "Heading2",
+        name: "Heading 2",
+        basedOn: "Normal",
+        next: "Normal",
+        quickFormat: true,
+        run: { size: 28, bold: true, font: "Arial" },
+        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 },
+      },
+    ],
+  },
+  sections: [
+    {
+      children: [
+        new Paragraph({
+          heading: HeadingLevel.HEADING_1,
+          children: [new TextRun("Title")],
+        }),
+      ],
+    },
+  ],
+});
+```
+
+### Lists (NEVER use unicode bullets)
+
+```javascript
+// WRONG
+new Paragraph({ children: [new TextRun("• Item")] });
+
+// CORRECT
+const doc = new Document({
+  numbering: {
+    config: [
+      {
+        reference: "bullets",
+        levels: [
+          {
+            level: 0,
+            format: LevelFormat.BULLET,
+            text: "*",
+            alignment: AlignmentType.LEFT,
+            style: { paragraph: { indent: { left: 720, hanging: 360 } } },
+          },
+        ],
+      },
+    ],
+  },
+  sections: [
+    {
+      children: [
+        new Paragraph({
+          numbering: { reference: "bullets", level: 0 },
+          children: [new TextRun("Bullet item")],
+        }),
+      ],
+    },
+  ],
+});
+```
+
+### Tables
+
+**CRITICAL: Tables need dual widths** — set both `columnWidths` on the table AND `width` on each cell.
+
+```javascript
+const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
+const borders = { top: border, bottom: border, left: border, right: border };
+
+new Table({
+  width: { size: 9360, type: WidthType.DXA },
+  columnWidths: [4680, 4680],
+  rows: [
+    new TableRow({
+      children: [
+        new TableCell({
+          borders,
+          width: { size: 4680, type: WidthType.DXA },
+          shading: { fill: "D5E8F0", type: ShadingType.CLEAR },
+          margins: { top: 80, bottom: 80, left: 120, right: 120 },
+          children: [new Paragraph({ children: [new TextRun("Cell")] })],
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**Width rules:** Always use `WidthType.DXA` (never PERCENTAGE). Table width = sum of columnWidths. Cell width must match corresponding columnWidth.
+
+### Images
+
+```javascript
+new Paragraph({
+  children: [
+    new ImageRun({
+      type: "png",
+      data: fs.readFileSync("image.png"),
+      transformation: { width: 200, height: 150 },
+      altText: { title: "Title", description: "Desc", name: "Name" },
+    }),
+  ],
+});
+```
+
+### Hyperlinks
+
+```javascript
+// External
+new Paragraph({
+  children: [
+    new ExternalHyperlink({
+      children: [new TextRun({ text: "Click here", style: "Hyperlink" })],
+      link: "https://example.com",
+    }),
+  ],
+});
+
+// Internal (bookmark + reference)
+new Paragraph({
+  heading: HeadingLevel.HEADING_1,
+  children: [new Bookmark({ id: "ch1", children: [new TextRun("Chapter 1")] })],
+});
+new Paragraph({
+  children: [
+    new InternalHyperlink({
+      children: [new TextRun({ text: "See Chapter 1", style: "Hyperlink" })],
+      anchor: "ch1",
+    }),
+  ],
+});
+```
+
+### Footnotes, Page Breaks, TOC, Headers/Footers
+
+```javascript
+// Footnotes
+const doc = new Document({
+  footnotes: { 1: { children: [new Paragraph("Source: Annual Report 2024")] } },
+  sections: [{ children: [new Paragraph({ children: [
+    new TextRun("Revenue grew 15%"), new FootnoteReferenceRun(1),
+  ]})]}]
+});
+
+// Page break
+new Paragraph({ children: [new PageBreak()] })
+
+// Table of contents
+new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })
+
+// Header + footer with page number
+headers: { default: new Header({ children: [new Paragraph({ children: [new TextRun("Header")] })] }) },
+footers: { default: new Footer({ children: [new Paragraph({ children: [
+  new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })
+]})]}) }
+```
+
+### Critical Rules for docx-js
+
+- **Set page size explicitly** — defaults to A4; US Letter = 12240 x 15840 DXA
+- **Landscape:** pass portrait dimensions, docx-js swaps internally
+- **Never use `\n`** — use separate Paragraph elements
+- **Never use unicode bullets** — use `LevelFormat.BULLET` with numbering config
+- **PageBreak must be in Paragraph**
+- **ImageRun requires `type`** — always specify png/jpg/etc
+- **Table width: use DXA** — never `WidthType.PERCENTAGE` (breaks in Google Docs)
+- **Tables need dual widths** — `columnWidths` AND cell `width` must match
+- **Table width = sum of columnWidths**
+- **Always add cell margins**
+- **Use `ShadingType.CLEAR`** — never SOLID for table shading
+- **Never use tables as dividers** — use border on Paragraph instead
+- **TOC requires HeadingLevel only** — no custom styles. Include `outlineLevel` for TOC.
+- **Override built-in styles** — use exact IDs: "Heading1", "Heading2", etc.
+
+---
+
+## Editing Existing Documents
+
+Follow all 3 steps in order.
+
+### Step 1: Unpack
+
+```bash
+python scripts/office/unpack.py document.docx unpacked/
+```
+
+### Step 2: Edit XML
+
+Edit files in `unpacked/word/`. Use "Claude" as the author for tracked changes and comments unless otherwise specified. **Use the Edit tool directly — do not write Python scripts for XML manipulation.**
+
+**Smart quotes — use XML entities for new content:**
+
+| Entity     | Character                     |
+| ---------- | ----------------------------- |
+| `‘` | ' (left single)               |
+| `’` | ' (right single / apostrophe) |
+| `“` | " (left double)               |
+| `”` | " (right double)              |
+
+**Adding comments:**
+
+```bash
+python scripts/comment.py unpacked/ 0 "Comment text"
+python scripts/comment.py unpacked/ 1 "Reply text" --parent 0
+python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"
+```
+
+### Step 3: Pack
+
+```bash
+python scripts/office/pack.py unpacked/ output.docx --original document.docx
+```
+
+### Tracked Changes XML Reference
+
+```xml
+<!-- Insertion -->
+<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
+  <w:r><w:t>inserted text</w:t></w:r>
+</w:ins>
+
+<!-- Deletion (use w:delText, not w:t) -->
+<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
+  <w:r><w:delText>deleted text</w:delText></w:r>
+</w:del>
+
+<!-- Minimal edit (replace "30" with "60") -->
+<w:r><w:t>The term is </w:t></w:r>
+<w:del w:id="1" w:author="Claude" w:date="...">
+  <w:r><w:delText>30</w:delText></w:r>
+</w:del>
+<w:ins w:id="2" w:author="Claude" w:date="...">
+  <w:r><w:t>60</w:t></w:r>
+</w:ins>
+<w:r><w:t> days.</w:t></w:r>
+```
+
+### Bundled Scripts
+
+| Script                       | Purpose                                    |
+| ---------------------------- | ------------------------------------------ |
+| `scripts/office/unpack.py`   | Extract and pretty-print .docx XML         |
+| `scripts/office/pack.py`     | Validate, repair, and repack into .docx    |
+| `scripts/office/validate.py` | Validate against ISO/ECMA schemas          |
+| `scripts/office/soffice.py`  | LibreOffice automation (convert, render)   |
+| `scripts/accept_changes.py`  | Accept all tracked changes via LibreOffice |
+| `scripts/comment.py`         | Add/manage comments in unpacked documents  |
+
+---
+
+## Dependencies
+
+- **pandoc**: Text extraction
+- **docx**: `npm install -g docx` (new documents)
+- **LibreOffice**: PDF conversion, tracked change acceptance
+- **Poppler**: `pdftoppm` for images
+- **defusedxml**: XML parsing (used by office toolkit)

package/.merlin-core/skills/general/docx/references/windows-setup.md

@@ -0,0 +1,27 @@
+# Windows Setup for DOCX Tools
+
+## Node.js (docx-js)
+
+```bash
+npm install -g docx
+```
+
+## System Dependencies
+
+### Pandoc (text extraction)
+
+1. Download from: https://pandoc.org/installing.html
+2. Install MSI package
+3. Verify: `pandoc --version`
+
+### LibreOffice (PDF conversion)
+
+1. Download from: https://www.libreoffice.org/download/
+2. Install to default location
+3. Verify: `soffice --version`
+
+### Poppler (pdftoppm for image conversion)
+
+1. Download from: https://github.com/ossamamehmood/Poppler-latest/releases
+2. Extract to `C:\poppler\`
+3. Add `C:\poppler\Library\bin\` to PATH

package/.merlin-core/skills/general/docx/scripts/__init__.py

@@ -0,0 +1 @@
+