@groupby/ai-dev 0.2.0 → 0.2.3

package/README.md

@@ -57,6 +57,7 @@ When installing a team's skills, you will be prompted to optionally include skil
 | Flag | Description |
 | --- | --- |
 | `--target <dir>` | Install into a specific directory (defaults to cwd) |
+| `--ai-dir <path>` | Override the AI skills/resources directory (defaults to `docs/ai`) |
 | `--dry-run` | Preview what would be installed without writing files |
 | `--force` | Overwrite existing files without prompting |
 | `--skip-existing` | Skip files that already exist |
@@ -65,8 +66,9 @@ When installing a team's skills, you will be prompted to optionally include skil
 
 1. **Discovery** — The CLI scans bundled `skills/` and `teams/` directories for `SKILL.md` files and reads their YAML frontmatter (name, description, etc.).
 2. **Client detection** — It checks the target project for known config directories (`.github/`, `.claude/`, `.agents/`) to determine which LLM clients are in use.
-3. **Installation** — Each selected skill is copied into `docs/ai/skills/<name>/` and a stub `SKILL.md` is generated in each client's skills directory pointing back to the full skill file.
+3. **Installation** — Each selected skill is copied into `<ai-dir>/skills/<name>/` (default: `docs/ai/skills/<name>/`) and a stub `SKILL.md` is generated in each client's skills directory pointing back to the full skill file.
 4. **Conflict handling** — If a file already exists and its content differs, you are prompted to overwrite or skip (unless `--force` or `--skip-existing` is set).
+5. **Path patching** — When `--ai-dir` is set to a non-default value, any `docs/ai/` references inside installed `.md` files are replaced with the custom path so LLMs can find resource files at runtime.
 
 ## Supported clients
 

package/dist/index.js

@@ -22,9 +22,9 @@ function parseFrontmatter(content) {
     content: parsed.content
   };
 }
-function generateStub(frontmatter, skillName) {
+function generateStub(frontmatter, skillName, aiDir = "docs/ai") {
   const body = `
-See \`docs/ai/skills/${skillName}/SKILL.md\` and follow closely.
+See \`${aiDir}/skills/${skillName}/SKILL.md\` and follow closely.
 `;
   return matter.stringify(body, frontmatter);
 }
@@ -266,6 +266,7 @@ async function detectClients(targetDir) {
 // src/lib/installer.ts
 import path3 from "path";
 import fs4 from "fs-extra";
+var DEFAULT_AI_DIR = "docs/ai";
 async function handleFile(srcPath, destPath, options, result, onConflict, contentOverride) {
   const relativeDest = path3.relative(options.targetDir, destPath);
   if (await fs4.pathExists(destPath)) {
@@ -309,6 +310,12 @@ async function handleFile(srcPath, destPath, options, result, onConflict, conten
     result.created.push(relativeDest);
   }
 }
+async function patchContent(srcPath, aiDir) {
+  if (aiDir === DEFAULT_AI_DIR) return void 0;
+  if (!srcPath.endsWith(".md")) return void 0;
+  const content = await fs4.readFile(srcPath, "utf-8");
+  return content.replaceAll(`${DEFAULT_AI_DIR}/`, `${aiDir}/`);
+}
 async function installSkill(skill, options, onConflict) {
   const result = {
     skill: skill.name,
@@ -316,14 +323,15 @@ async function installSkill(skill, options, onConflict) {
     skipped: [],
     overwritten: []
   };
-  const destFolder = path3.join(options.targetDir, "docs", "ai", "skills", skill.name);
+  const destFolder = path3.join(options.targetDir, options.aiDir, "skills", skill.name);
   const sourceFiles = await fs4.readdir(skill.sourcePath);
   for (const file of sourceFiles) {
     const srcFile = path3.join(skill.sourcePath, file);
     const stat = await fs4.stat(srcFile);
     if (stat.isFile()) {
       const destFile = path3.join(destFolder, file);
-      await handleFile(srcFile, destFile, options, result, onConflict);
+      const contentOverride = await patchContent(srcFile, options.aiDir);
+      await handleFile(srcFile, destFile, options, result, onConflict, contentOverride);
     }
   }
   for (const client of options.clients) {
@@ -333,7 +341,7 @@ async function installSkill(skill, options, onConflict) {
       skill.name,
       "SKILL.md"
     );
-    const stubContent = generateStub(skill.frontmatter, skill.name);
+    const stubContent = generateStub(skill.frontmatter, skill.name, options.aiDir);
     await handleFile("", stubPath, options, result, onConflict, stubContent);
   }
   return result;
@@ -355,14 +363,15 @@ async function installResources(toolset, options, onConflict) {
   if (!toolset.hasResources) return result;
   const entries = await fs4.readdir(toolset.resourcesPath);
   const resourceFiles = entries.filter((e) => e !== "README.md");
-  const destDir = path3.join(options.targetDir, "docs", "ai", "resources");
+  const destDir = path3.join(options.targetDir, options.aiDir, "resources");
   const fileResult = { skill: toolset.name, created: [], skipped: [], overwritten: [] };
   for (const file of resourceFiles) {
     const srcFile = path3.join(toolset.resourcesPath, file);
     const stat = await fs4.stat(srcFile);
     if (!stat.isFile()) continue;
     const destFile = path3.join(destDir, file);
-    await handleFile(srcFile, destFile, options, fileResult, onConflict);
+    const contentOverride = await patchContent(srcFile, options.aiDir);
+    await handleFile(srcFile, destFile, options, fileResult, onConflict, contentOverride);
   }
   result.created = fileResult.created;
   result.skipped = fileResult.skipped;
@@ -371,7 +380,7 @@ async function installResources(toolset, options, onConflict) {
 }
 
 // src/lib/prompts.ts
-import { select, checkbox, confirm } from "@inquirer/prompts";
+import { select, checkbox, confirm, input } from "@inquirer/prompts";
 import chalk2 from "chalk";
 async function promptSelectSkills(skills) {
   const librarySkills = skills.filter((s) => s.sourceType === "library");
@@ -457,12 +466,22 @@ async function promptIncludeLibrary() {
     default: false
   });
 }
-async function promptConfirmInstall(skills, clients, targetDir) {
+async function promptInstallDir() {
+  const raw = await input({
+    message: "Install location for AI skills and resources:",
+    default: "docs/ai"
+  });
+  return raw.replace(/\/+$/, "") || "docs/ai";
+}
+async function promptConfirmInstall(skills, clients, targetDir, aiDir = "docs/ai") {
   console.log();
   console.log(chalk2.bold("Install summary:"));
   console.log(`  Skills: ${skills.map((s) => s.name).join(", ")}`);
   console.log(`  Clients: ${clients.map((c) => c.name).join(", ") || chalk2.dim("none")}`);
   console.log(`  Target: ${targetDir}`);
+  if (aiDir !== "docs/ai") {
+    console.log(`  AI directory: ${aiDir}`);
+  }
   console.log();
   return confirm({ message: "Proceed with installation?", default: true });
 }
@@ -485,6 +504,14 @@ function formatTeamName2(name) {
 }
 
 // src/commands/install.ts
+function normalizeAiDir(raw) {
+  const trimmed = raw.replace(/\/+$/, "") || DEFAULT_AI_DIR;
+  if (path4.isAbsolute(trimmed)) {
+    console.log(chalk3.red(`--ai-dir must be a relative path, got: ${trimmed}`));
+    process.exit(1);
+  }
+  return trimmed;
+}
 function printResults(results, options, resourceResult) {
   const prefix = options.dryRun ? chalk3.yellow("[DRY RUN] ") : "";
   const createdWord = options.dryRun ? "would create" : "created";
@@ -525,6 +552,7 @@ async function installSkillCmd(name, _opts, cmd) {
   const targetDir = path4.resolve(
     parentOpts.target || process.cwd()
   );
+  const aiDir = normalizeAiDir(parentOpts.aiDir || DEFAULT_AI_DIR);
   const skill = await findSkill(name);
   if (!skill) {
     const all = await discoverSkills();
@@ -541,6 +569,7 @@ async function installSkillCmd(name, _opts, cmd) {
   }
   const options = {
     targetDir,
+    aiDir,
     clients,
     force,
     skipExisting,
@@ -564,6 +593,7 @@ async function installTeamCmd(name, _opts, cmd) {
   const targetDir = path4.resolve(
     parentOpts.target || process.cwd()
   );
+  const aiDir = normalizeAiDir(parentOpts.aiDir || DEFAULT_AI_DIR);
   const teams = await discoverTeams();
   const team = teams.find(
     (t) => t.name === name || t.name.toLowerCase() === name.toLowerCase()
@@ -589,6 +619,7 @@ async function installTeamCmd(name, _opts, cmd) {
   }
   const options = {
     targetDir,
+    aiDir,
     clients,
     force,
     skipExisting,
@@ -609,6 +640,7 @@ async function installToolsetCmd(name, _opts, cmd) {
   const targetDir = path4.resolve(
     parentOpts.target || process.cwd()
   );
+  const aiDir = normalizeAiDir(parentOpts.aiDir || DEFAULT_AI_DIR);
   const toolset = await findToolset(name);
   if (!toolset) {
     const allToolsets = await discoverToolsets();
@@ -627,6 +659,7 @@ async function installToolsetCmd(name, _opts, cmd) {
   }
   const options = {
     targetDir,
+    aiDir,
     clients,
     force,
     skipExisting,
@@ -640,11 +673,18 @@ async function installToolsetCmd(name, _opts, cmd) {
   const results = await installSkills(toolset.skills, options, conflictHandler);
   printResults(results, options, resourceResult);
 }
+var INHERITED_OPTIONS_HELP = `
+Parent options (pass before subcommand):
+  --force            Overwrite existing files without prompting
+  --skip-existing    Skip files that already exist without prompting
+  --dry-run          Show what would be installed without writing files
+  --target <dir>     Install to a different directory (default: CWD)
+  --ai-dir <path>    Override the AI skills/resources directory (default: docs/ai)`;
 function registerInstallCommand(program2) {
-  const install = program2.command("install").description("Install skills").option("--force", "Overwrite existing files without prompting").option("--skip-existing", "Skip files that already exist without prompting").option("--dry-run", "Show what would be installed without writing files").option("--target <dir>", "Install to a different directory (default: CWD)");
-  install.command("skill <name>").description("Install a specific skill").action(installSkillCmd);
-  install.command("team <name>").description("Install all skills for a team").action(installTeamCmd);
-  install.command("toolset <name>").description("Install all skills and resources for a toolset").action(installToolsetCmd);
+  const install = program2.command("install").description("Install skills").option("--force", "Overwrite existing files without prompting").option("--skip-existing", "Skip files that already exist without prompting").option("--dry-run", "Show what would be installed without writing files").option("--target <dir>", "Install to a different directory (default: CWD)").option("--ai-dir <path>", "Override the AI skills/resources directory (default: docs/ai)");
+  install.command("skill <name>").description("Install a specific skill").addHelpText("after", INHERITED_OPTIONS_HELP).action(installSkillCmd);
+  install.command("team <name>").description("Install all skills for a team").addHelpText("after", INHERITED_OPTIONS_HELP).action(installTeamCmd);
+  install.command("toolset <name>").description("Install all skills and resources for a toolset").addHelpText("after", INHERITED_OPTIONS_HELP).action(installToolsetCmd);
 }
 
 // src/commands/interactive.ts
@@ -757,20 +797,32 @@ async function runInteractive() {
     const selectedSkills = await promptSelectSkills(allSkills);
     const detected = await detectClients(targetDir);
     const clients = await promptSelectClients(ALL_CLIENTS, detected);
-    const confirmed = await promptConfirmInstall(selectedSkills, clients, targetDir);
+    const aiDir = await promptInstallDir();
+    const confirmed = await promptConfirmInstall(selectedSkills, clients, targetDir, aiDir);
     if (!confirmed) {
       console.log(chalk4.dim("Cancelled."));
       return;
     }
     const options = {
       targetDir,
+      aiDir,
       clients,
       force: false,
       skipExisting: false,
       dryRun: false
     };
     const results = await installSkills(selectedSkills, options, promptConflict);
-    printResults2(results, options);
+    let resourceResult;
+    const toolsetNames = new Set(
+      selectedSkills.filter((s) => s.sourceType === "toolset" && s.toolsetName).map((s) => s.toolsetName)
+    );
+    for (const tsName of toolsetNames) {
+      const toolset = await findToolset(tsName);
+      if (toolset && toolset.hasResources) {
+        resourceResult = await installResources(toolset, options, promptConflict);
+      }
+    }
+    printResults2(results, options, resourceResult);
   } else if (action === "install-team") {
     const teams = await discoverTeams();
     if (teams.length === 0) {
@@ -787,20 +839,32 @@ async function runInteractive() {
     }
     const detected = await detectClients(targetDir);
     const clients = await promptSelectClients(ALL_CLIENTS, detected);
-    const confirmed = await promptConfirmInstall(skillsToInstall, clients, targetDir);
+    const aiDir = await promptInstallDir();
+    const confirmed = await promptConfirmInstall(skillsToInstall, clients, targetDir, aiDir);
     if (!confirmed) {
       console.log(chalk4.dim("Cancelled."));
       return;
     }
     const options = {
       targetDir,
+      aiDir,
       clients,
       force: false,
       skipExisting: false,
       dryRun: false
     };
     const results = await installSkills(skillsToInstall, options, promptConflict);
-    printResults2(results, options);
+    let resourceResult;
+    const toolsetNames = new Set(
+      skillsToInstall.filter((s) => s.sourceType === "toolset" && s.toolsetName).map((s) => s.toolsetName)
+    );
+    for (const tsName of toolsetNames) {
+      const toolset = await findToolset(tsName);
+      if (toolset && toolset.hasResources) {
+        resourceResult = await installResources(toolset, options, promptConflict);
+      }
+    }
+    printResults2(results, options, resourceResult);
   } else if (action === "install-toolset") {
     const toolsets = await discoverToolsets();
     if (toolsets.length === 0) {
@@ -810,13 +874,15 @@ async function runInteractive() {
     const toolset = await promptSelectToolset(toolsets);
     const detected = await detectClients(targetDir);
     const clients = await promptSelectClients(ALL_CLIENTS, detected);
-    const confirmed = await promptConfirmInstall(toolset.skills, clients, targetDir);
+    const aiDir = await promptInstallDir();
+    const confirmed = await promptConfirmInstall(toolset.skills, clients, targetDir, aiDir);
     if (!confirmed) {
       console.log(chalk4.dim("Cancelled."));
       return;
     }
     const options = {
       targetDir,
+      aiDir,
       clients,
       force: false,
       skipExisting: false,
@@ -846,6 +912,7 @@ Examples:
   $ npx @groupby/ai-dev install skill frontend-design Install a single skill
   $ npx @groupby/ai-dev install team brain-studio     Install all team skills
   $ npx @groupby/ai-dev install toolset rzlv-flow     Install all skills + resources for a toolset
-  $ npx @groupby/ai-dev install team brain-studio --dry-run`
+  $ npx @groupby/ai-dev install team brain-studio --dry-run
+  $ npx @groupby/ai-dev install skill frontend-design --ai-dir .ai`
 );
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Interactive installer for Rezolve Ai development skills",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "toolsets/"
   ],
   "scripts": {
-    "prebuild": "cp -r ../skills ./skills && cp -r ../teams ./teams && cp -r ../toolsets ./toolsets",
+    "prebuild": "rm -rf skills teams toolsets && cp -r ../skills ./skills && cp -r ../teams ./teams && cp -r ../toolsets ./toolsets",
     "build": "tsup",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
@@ -29,7 +29,7 @@
     "node": ">=18"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/toolsets/rzlv-flow/README.md

@@ -4,20 +4,41 @@ A toolset of modular, composable skills for Jira and Confluence developer workfl
 
 Each skill is standalone and can be installed individually or as a complete suite.
 
+## Quick Start
+
+```bash
+# 1. Install all skills + resources
+npx @groupby/ai-dev install toolset rzlv-flow
+
+# 2. Configure Atlassian MCP (see docs/mcp-setup.md)
+#    Add atlassian-rovo config to .vscode/mcp.json
+
+# 3. Use — ask your AI assistant:
+#    "Start my day"           → daily triage
+#    "Focus on PROJ-123"      → ticket deep-dive
+#    "Wrap up PROJ-123"       → wrap & sync
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
+
 ## Skills
 
 | Skill | Description | Status |
 |-------|-------------|--------|
-| `jira-daily-triage` | Start-of-day ticket triage with sprint detection | Planned |
-| `jira-ticket-focus` | Deep-load a ticket with full context | Planned |
-| `jira-wrap-sync` | Wrap up work, draft comment, multi-action sync | Planned |
-| `jira-ticket-trace` | Trace code back to Jira requirements | Planned |
-| `jira-comment` | Add a comment to a Jira ticket with FCMP safety | Planned |
-| `jira-status` | Change ticket status with transition validation | Planned |
-| `jira-sprint-status` | Sprint status report with completion metrics | Planned |
-| `jira-sync` | Force-sync local Jira context with remote state | Planned |
+| `jira-daily-triage` | Start-of-day ticket triage with sprint detection | Complete |
+| `jira-ticket-focus` | Deep-load a ticket with full context | Complete |
+| `jira-wrap-sync` | Wrap up work, draft comment, multi-action sync | Complete |
+| `jira-ticket-trace` | Trace code back to Jira requirements | Complete |
+| `jira-comment` | Add a comment to a Jira ticket with FCMP safety | Complete |
+| `jira-status` | Change ticket status with transition validation | Complete |
+| `jira-sprint-status` | Sprint status report with completion metrics | Complete |
+| `jira-sync` | Force-sync local Jira context with remote state | Complete |
 | `atlassian-orchestrator` | Pull surrounding ticket context and create structures | Complete |
 | `context-analyst` | Transform meeting transcripts into structured docs | Complete |
+| `confluence-publish` | Publish local markdown to Confluence with Leaf Bundle mirrors | Complete |
+| `confluence-fetch` | Pull a Confluence page into a local markdown mirror | Complete |
+
+> **Note:** `confluence-publish` provides lightweight ad-hoc publishing to Confluence. For bulk structured sync of `_docs/` folders following epic hierarchy, use `atlassian-orchestrator` Mode 3 instead.
 
 ## Prerequisites
 
@@ -38,7 +59,16 @@ npx @groupby/ai-dev install toolset rzlv-flow       # All skills + resources
 npx @groupby/ai-dev install skill jira-daily-triage   # Individual skill
 ```
 
-> **Note:** CLI toolset support is coming soon. For now, skills can be copied manually from this repository into your project's `docs/ai/skills/` directory, and resources into `docs/ai/resources/`.
+Common options:
+
+| Flag | Description |
+|------|-------------|
+| `--target <dir>` | Install into a specific directory (defaults to cwd) |
+| `--dry-run` | Preview what would be installed without writing files |
+| `--force` | Overwrite existing files without prompting |
+| `--skip-existing` | Skip files that already exist |
+
+You can also copy skills manually from this repository into `docs/ai/skills/` and resources into `docs/ai/resources/`.
 
 ## BMAD Compatibility
 
@@ -55,3 +85,18 @@ Skills reference shared resource files installed to `docs/ai/resources/` in your
 | `confluence-file-structure.md` | Leaf Bundle pattern for Confluence page mirrors |
 | `sync-state-format.md` | YAML frontmatter schema for ticket and page files |
 | `confluence-page-templates/` | Starter scaffolds for Confluence pages (initiative overview, strategic context, technical architecture, decisions) |
+
+## MCP Setup Automation
+
+MCP server configuration is currently manual — see [docs/mcp-setup.md](docs/mcp-setup.md) for step-by-step instructions (~5 minutes). Automated MCP configuration via the CLI is a future enhancement.
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [docs/getting-started.md](docs/getting-started.md) | Quick walkthrough: install → configure → use |
+| [docs/mcp-setup.md](docs/mcp-setup.md) | Atlassian and GitHub MCP server configuration |
+
+## Contributing
+
+See the [architecture documentation](../../docs/architecture/README.md) for repo structure, skill authoring guides, and conventions.

package/toolsets/rzlv-flow/resources/confluence-file-structure.md

@@ -1,6 +1,6 @@
 # Confluence File Structure — Local Page Mirrors
 
-**Pattern:** Dual-mode local mirrors for Confluence pages
+**Pattern:** Leaf Bundle local mirrors for Confluence pages
 
 ---
 
@@ -15,6 +15,30 @@ Both modes follow the FCMP protocol for safe sync operations and preserve manual
 
 ---
 
+## Leaf Bundle Pattern
+
+Every Confluence page is stored as a **directory** containing an `index.md` file — never as a standalone `.md` file. This is called the Leaf Bundle pattern.
+
+### Why Folders, Not Files?
+
+- **Child pages** — A Confluence page can have child pages. The folder naturally represents this hierarchy; child pages become subdirectories.
+- **Assets** — Pages may include attachments, images, or diagrams. These are stored alongside `index.md` in the same folder.
+- **Hierarchy expansion** — New child pages can be added without restructuring. A flat file cannot grow into a parent.
+
+### DO NOT / DO
+
+```
+❌ DO NOT create flat files:
+docs/confluence/rezolve/ENG/strategic-context.md
+
+✅ DO create Leaf Bundle directories:
+docs/confluence/rezolve/ENG/strategic-context/index.md
+```
+
+This rule applies to **all** Confluence page mirrors, in both structured and flexible modes.
+
+---
+
 ## Base Path
 
 ```
@@ -37,27 +61,34 @@ docs/confluence/{instance}/{space}/
 └── {initiative-name}/
     ├── index.md                          # Initiative Overview
     └── {epic-name}/
-        ├── overview.md
-        ├── technical-architecture.md
-        ├── decisions.md
-        ├── strategic-context.md
-        ├── research-and-findings.md         # Created only if relevant content exists
-        ├── assumptions.md                   # Created only if relevant content exists
-        └── implementation-guidance.md
+        ├── overview/
+        │   └── index.md
+        ├── technical-architecture/
+        │   └── index.md
+        ├── decisions/
+        │   └── index.md
+        ├── strategic-context/
+        │   └── index.md
+        ├── research-and-findings/         # Created only if relevant content exists
+        │   └── index.md
+        ├── assumptions/                   # Created only if relevant content exists
+        │   └── index.md
+        └── implementation-guidance/
+            └── index.md
 ```
 
 ### Page Types
 
-| Page Type | Source | Description |
-|-----------|--------|-------------|
-| Initiative Overview (`index.md` at initiative root) | Initiative metadata | Top-level overview: goals, epic breakdown, navigation |
-| `overview.md` | Epic `_docs/` | High-level epic overview and goals |
-| `technical-architecture.md` | Epic `_docs/` | Architecture decisions and technical design |
-| `decisions.md` | Epic `_docs/` | Decision log and rationale |
-| `strategic-context.md` | Epic `_docs/` | Business context and strategic alignment |
-| `research-and-findings.md` | Epic `_docs/` | User research, discoveries, and clarifications* |
-| `assumptions.md` | Epic `_docs/` | Assumptions with confidence levels and validation status* |
-| `implementation-guidance.md` | Epic `_docs/` | High-value technical guides for development |
+| Page Type | Folder | Source | Description |
+|-----------|--------|--------|-------------|
+| Initiative Overview | `index.md` (at initiative root) | Initiative metadata | Top-level overview: goals, epic breakdown, navigation |
+| Overview | `overview/index.md` | Epic `_docs/` | High-level epic overview and goals |
+| Technical Architecture | `technical-architecture/index.md` | Epic `_docs/` | Architecture decisions and technical design |
+| Decisions | `decisions/index.md` | Epic `_docs/` | Decision log and rationale |
+| Strategic Context | `strategic-context/index.md` | Epic `_docs/` | Business context and strategic alignment |
+| Research & Findings | `research-and-findings/index.md` | Epic `_docs/` | User research, discoveries, and clarifications* |
+| Assumptions | `assumptions/index.md` | Epic `_docs/` | Assumptions with confidence levels and validation status* |
+| Implementation Guidance | `implementation-guidance/index.md` | Epic `_docs/` | High-value technical guides for development |
 
 \* Created only if the source material includes relevant content.
 
@@ -84,10 +115,11 @@ Used for ad-hoc documentation, user-specified locations, and non-epic-based cont
 ```
 docs/confluence/{instance}/{space}/
 └── {user-specified-path}/
-    └── {page-name}.md
+    └── {page-name}/
+        └── index.md
 ```
 
-No predefined structure — adapts to the user's needs.
+No predefined structure beyond the Leaf Bundle requirement — adapts to the user's needs.
 
 ### When to Use
 
@@ -141,15 +173,28 @@ Skills using flexible mode should ask:
 
 ---
 
+## Confluence Link Format
+
+When constructing Confluence URLs:
+
+- Replace spaces in page titles with `+`
+- Use the `/wiki/display/{SPACE}/{Title}` format for display links
+- Use the `/wiki/spaces/{SPACE}/pages/{pageId}` format for direct links
+
+Example: `https://company.atlassian.net/wiki/display/ENG/Technical+Architecture`
+
+---
+
 ## Page File Format
 
-Each local Confluence mirror file uses YAML frontmatter for sync metadata:
+Each local Confluence mirror file (`index.md` inside a Leaf Bundle directory) uses YAML frontmatter for sync metadata:
 
 ```yaml
 ---
 sync:
   confluence_page_id: "123456789"
   confluence_url: "https://company.atlassian.net/wiki/spaces/ENG/pages/123456789"
+  confluence_title: "Technical Architecture"
   space: "ENG"
   parent_page_id: "987654321"
   last_synced: "2025-12-11T10:30:00Z"
@@ -163,6 +208,9 @@ source:
   jira_ticket: "PROJ-120"
   doc_type: "technical-architecture"
   generated_from: "docs/jira/rezolve/PROJ/user-authentication/_docs/technical-architecture.md"
+  bmad_docs_referenced:
+    - "docs/jira/rezolve/PROJ/PROJ-120-user-auth/_docs/technical-architecture.md"
+  jira_initiative_key: "PROJ-100"
 
   # For flexible mode
   # origin: "manual"
@@ -174,6 +222,64 @@ source:
 Page content in markdown, converted to Confluence storage format during sync.
 ```
 
-See `sync-state-format.md` for full frontmatter schema details.
+### Frontmatter Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sync.confluence_page_id` | string | After first sync | Confluence page ID |
+| `sync.confluence_url` | string | After first sync | Full page URL |
+| `sync.confluence_title` | string | Yes | Exact title as it appears in Confluence (used for page lookups) |
+| `sync.space` | string | Yes | Confluence space key |
+| `sync.parent_page_id` | string | Yes | Parent page ID in Confluence |
+| `sync.last_synced` | ISO8601 | After first sync | Last sync timestamp |
+| `sync.version` | number | After first sync | Confluence page version for optimistic locking |
+| `sync.remote_updated` | ISO8601 | After first sync | Last remote change timestamp |
+| `mode` | enum | Yes | `structured` or `flexible` |
+| `source.jira_ticket` | string | Structured | Associated Jira ticket key |
+| `source.doc_type` | string | Structured | Page type (overview, technical-architecture, decisions, strategic-context) |
+| `source.generated_from` | string | Structured | Path to the `_docs/` source file |
+| `source.bmad_docs_referenced` | string[] | No | BMAD source docs used to generate the page (traceability) |
+| `source.jira_initiative_key` | string | No | Related Jira initiative key (cross-linking) |
+| `source.origin` | string | Flexible | Origin skill or `manual` |
+| `source.linked_jira` | string | Flexible | Optionally linked Jira ticket |
+
+> **Note on field naming:** The source rzlv-flow repo uses flat root-level fields (e.g. `confluence_space_key: "ENG"`). This toolset uses nested fields under `sync.*` for consistency with the Jira file schema. Both conventions represent the same data; skills should follow the nested format documented here.
+
+### Post-Sync Frontmatter Example
+
+**Before first sync (draft state):**
+```yaml
+---
+sync:
+  confluence_title: "Technical Architecture"
+  space: "ENG"
+  parent_page_id: "987654321"
+mode: "structured"
+source:
+  jira_ticket: "PROJ-120"
+  doc_type: "technical-architecture"
+  generated_from: "docs/jira/rezolve/PROJ/PROJ-120-user-auth/_docs/technical-architecture.md"
+---
+```
+
+**After first sync (populated by sync operation):**
+```yaml
+---
+sync:
+  confluence_page_id: "123456789"
+  confluence_url: "https://company.atlassian.net/wiki/spaces/ENG/pages/123456789"
+  confluence_title: "Technical Architecture"
+  space: "ENG"
+  parent_page_id: "987654321"
+  last_synced: "2025-12-11T10:30:00Z"
+  version: 1
+  remote_updated: "2025-12-11T10:30:00Z"
+mode: "structured"
+source:
+  jira_ticket: "PROJ-120"
+  doc_type: "technical-architecture"
+  generated_from: "docs/jira/rezolve/PROJ/PROJ-120-user-auth/_docs/technical-architecture.md"
+---
+```
 
-<!-- TODO: Pull additional detail from full rzlv-flow repo for Leaf Bundle pattern specifics and doc-type-mapping rules if available -->
+See `sync-state-format.md` for the full frontmatter schema and worked examples.