@vpxa/aikit 0.1.67 → 0.1.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/scaffold/general/skills/c4-architecture/references/c4-syntax.md

@@ -484,6 +484,24 @@ Keep diagrams under 15 elements. Split complex architectures into multiple focus
 **Element Ordering:**
 Elements appear in the order they are defined. Reorder statements to adjust layout.
 
+### Special Characters
+
+Node labels and subgraph titles containing `@`, `/`, `#`, or other special characters must be quoted:
+
+```mermaid
+%% WRONG — will break parsing
+subgraph @scope/package
+  NodeA[@scope/lib]
+end
+
+%% CORRECT — quoted labels
+subgraph ScopePkg["@scope/package"]
+  NodeA["@scope/lib"]
+end
+```
+
+Use plain alphanumeric strings for node IDs (aliases). Put display names with special characters inside `["..."]`.
+
 ### Alternative Tools
 
 For features Mermaid doesn't support, consider:

package/scaffold/general/skills/docs/SKILL.md

@@ -206,6 +206,22 @@ How to confirm it worked.
 Common issues and solutions.
 ```
 
+### Decision Index Template (`docs/decisions/index.md`)
+
+```markdown
+# Architecture Decision Record Index
+
+This page is the ADR log for the project. IDs are assigned sequentially as decisions are recorded.
+
+## Index
+
+| ID | Title | Status | Date | Source |
+| --- | --- | --- | --- | --- |
+| ADR-001 | {Decision title} | {Accepted/Proposed/Deprecated/Superseded} | {YYYY-MM-DD} | [{flow-topic}]({relative-path-to-flow-artifact}) |
+```
+
+The **Source** column links to the flow artifact (typically `design.md` or `design-decisions.md`) where the decision was originally designed. Use the flow's run directory path relative to the index file location (e.g., `../../.flows/{topic}/{artifacts}/design.md`). If the decision was made outside a flow, use "Manual" or link to the relevant discussion.
+
 ### Reference Template (`docs/reference/{topic}.md`)
 
 ```markdown
@@ -229,6 +245,7 @@ Brief description of what this reference covers.
 - All ADRs live in `docs/decisions/`
 - When the docs-sync step detects an architecture decision was made during the flow, delegate to `adr-skill`
 - After `adr-skill` creates/updates an ADR, update `docs/decisions/index.md`
+- Include the Source column linking to the flow artifact where the decision was designed.
 - Cross-reference ADRs from component docs where relevant
 
 ### `c4-architecture` Integration
@@ -237,6 +254,14 @@ Brief description of what this reference covers.
 - Use Mermaid format for docs files (not HTML) — markdown renders in GitHub
 - Reference diagrams from component docs
 
+### Mermaid Syntax Rules
+
+When generating Mermaid diagrams in documentation:
+
+- **Quote node labels containing special characters** — Names with `@`, `/`, or other special characters must be wrapped in double quotes inside square brackets: `subgraph Commons["@scope/package-name"]`, `NodeId["@org/lib"]`
+- **Quote subgraph titles with special characters** — `subgraph Title["@scope/name"]` not `subgraph @scope/name`
+- Node IDs (aliases) must not contain special characters — use plain alphanumeric IDs and put the display name in `["..."]`
+
 ## Project Knowledge Acquisition
 
 Produces seven populated documents in `docs/architecture/` covering everything needed to work effectively on the project — stack, structure, design, conventions, integrations, testing, and concerns.
@@ -431,7 +456,7 @@ docs/
 │   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
 │   └── components/        ← From analyze_symbols per major component
 ├── decisions/
-│   └── index.md           ← ADR log (delegate to adr-skill)
+│   └── index.md           ← ADR log with Source column linking to flow artifacts
 ├── guides/
 │   └── testing.md         ← From analyze_patterns test info
 └── reference/
@@ -483,6 +508,25 @@ Follow these rules when generating documentation content. Adapted from *The Elem
 - **No summary closers** — Do not end every paragraph by restating what it just said
 - **Consistent terminology** — Pick one term and use it throughout; do not alternate synonyms for variety
 
+## Link Rules
+
+### Relative Path Correctness
+
+All links in generated docs must be correct relative to the file that contains them. Compute the path from the target doc's directory, not from the project root.
+
+| Doc location | Link to `src/types/index.ts` | Link to `.flows/topic/artifacts/design.md` |
+|---|---|---|
+| `docs/README.md` | `../src/types/index.ts` | `../.flows/topic/artifacts/design.md` |
+| `docs/architecture/overview.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
+| `docs/decisions/index.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
+| `docs/reference/api.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
+
+**Rules:**
+1. Count the directory depth from the doc file to `docs/`, then add `../` to reach the project root
+2. Verify every link target exists before writing it — use `find({ pattern })` if unsure
+3. Never use absolute paths in documentation — always relative
+4. Test links mentally: from `docs/architecture/overview.md`, `../../` reaches the project root
+
 ## Anti-Patterns
 
 ### Documentation Maintenance