@flydocs/cli 0.6.0-alpha.5 → 0.6.0-alpha.7

package/template/flydocs/knowledge/INDEX.md

@@ -4,97 +4,82 @@
 AGENT INSTRUCTIONS:
 - Scan this file FIRST when looking for existing knowledge
 - Use descriptions to assess relevance before loading full docs
-- Update this index when adding new knowledge docs
+- Update this index when adding or modifying knowledge docs
+- Always use real dates, never leave as YYYY-MM-DD
 -->
 
 ## Quick Reference
 
-| Category | Count | Last Updated |
-|----------|-------|--------------|
-| Decisions | 0 | - |
-| Features | 0 | - |
-| Notes | 0 | - |
-| Product | 2 | YYYY-MM-DD |
+| Category  | Count | Last Updated |
+| --------- | ----- | ------------ |
+| Decisions | 0     | -            |
+| Features  | 0     | -            |
+| Notes     | 0     | -            |
+| Product   | 2     | -            |
 
 ---
 
-## 📋 Decisions (ADRs)
+## Decisions (ADRs)
 
-Architecture Decision Records - why we made key technical choices.
+Architecture Decision Records — why we made key technical choices.
 
-| ID | Title | Status | Date |
-|----|-------|--------|------|
-| - | No decisions recorded yet | - | - |
+| ID  | Title                     | Status | Date |
+| --- | ------------------------- | ------ | ---- |
+| -   | No decisions recorded yet | -      | -    |
 
 <!-- Example:
-| 001 | Use Convex for Backend | Accepted | 2024-01-15 |
-  → Explains why we chose Convex over traditional REST API
+| 001 | Use Convex for Backend | Accepted | 2026-01-15 |
+  -> Explains why we chose Convex over traditional REST API
 -->
 
 ---
 
-## 🔧 Features
+## Features
 
 Documentation for complex features that need more than a spec.
 
-| Feature | Description | Last Updated |
-|---------|-------------|--------------|
-| - | No feature docs yet | - |
+| Feature | Description         | Last Updated |
+| ------- | ------------------- | ------------ |
+| -       | No feature docs yet | -            |
 
 <!-- Example:
-| auth-system | Complete auth flow documentation | 2024-02-01 |
-  → OAuth setup, session handling, role-based access
+| auth-system | Complete auth flow documentation | 2026-02-01 |
+  -> OAuth setup, session handling, role-based access
 -->
 
 ---
 
-## 📝 Notes
+## Notes
 
 Technical discoveries, gotchas, learnings.
 
-| Topic | Description | Added |
-|-------|-------------|-------|
-| - | No notes yet | - |
+| Topic | Description  | Added |
+| ----- | ------------ | ----- |
+| -     | No notes yet | -     |
 
 <!-- Example:
-| api-rate-limits | Third-party API quirks and workarounds | 2024-01-20 |
-  → Stripe webhook retries, Figma API limits, etc.
+| api-rate-limits | Third-party API quirks and workarounds | 2026-01-20 |
+  -> Stripe webhook retries, Figma API limits, etc.
 -->
 
 ---
 
-## 👥 Product
+## Product
 
 User research and product documentation.
 
-| Document | Description | Last Updated |
-|----------|-------------|--------------|
-| personas.md | Target user profiles | YYYY-MM-DD |
-| user-flows.md | Key user journeys | YYYY-MM-DD |
+| Document      | Description          | Last Updated |
+| ------------- | -------------------- | ------------ |
+| personas.md   | Target user profiles | -            |
+| user-flows.md | Key user journeys    | -            |
 
 ---
 
 ## How to Add Knowledge
 
-### New Decision (ADR)
-```bash
-# Create: flydocs/knowledge/decisions/NNN-title.md
-# Update: This index with new entry
-```
-
-### New Feature Doc
-```bash
-# Create: flydocs/knowledge/features/feature-name.md
-# Update: This index with new entry
-```
-
-### New Note
-```bash
-# Create: flydocs/knowledge/notes/topic-name.md
-# Update: This index with new entry
-```
-
----
-
-*Last Updated: YYYY-MM-DD*
-
+1. Choose the category: decision, feature, note, or product
+2. Copy the template from `templates/<category>.md`
+3. Fill in the frontmatter (title, created date, related issues)
+4. Write the content following the template structure
+5. Add an entry to this index with a concise description
+6. Use the `/knowledge` command for a guided flow

package/template/flydocs/knowledge/README.md

@@ -6,42 +6,78 @@ This directory contains project knowledge that accumulates over time.
 
 ```
 knowledge/
-├── INDEX.md      # Start here - inventory of all knowledge
-├── decisions/    # Architecture Decision Records (ADRs)
-├── features/     # Complex feature documentation
-├── notes/        # Technical discoveries and learnings
-└── product/      # User research and product docs
+├── INDEX.md       # Start here — inventory of all knowledge
+├── templates/     # Structural templates for each category
+├── decisions/     # Architecture Decision Records (ADRs)
+├── features/      # Complex feature documentation
+├── notes/         # Technical discoveries and learnings
+└── product/       # User research and product docs
 ```
 
-## When to Add Knowledge
+## Templates
+
+Use templates from `templates/` when creating new knowledge docs. Each template includes
+a frontmatter block with required metadata fields.
+
+### Required Frontmatter
+
+All knowledge docs must include YAML frontmatter:
+
+```yaml
+---
+title: "Descriptive title"
+created: 2026-03-17
+lastUpdated: 2026-03-17
+relatedIssues: [FLY-123, FLY-456]
+---
+```
+
+Additional fields vary by category — see the template for each type.
+
+**Always update `lastUpdated`** when modifying an existing doc.
+
+## When to Create Knowledge
 
 ### Decisions (`decisions/`)
+
 Add an ADR when you make a significant technical choice:
+
 - Choosing a framework or library
 - Designing a system architecture
 - Establishing a pattern that others should follow
+- Rejecting an approach (document why, so others don't repeat the investigation)
 
 **Format**: `NNN-title.md` (e.g., `001-use-convex.md`)
+**Template**: `templates/decision.md`
 
 ### Features (`features/`)
+
 Add feature documentation when:
+
 - A feature is too complex for just a spec
 - Multiple specs relate to one system
 - Future developers will need deep context
 
 **Format**: `feature-name.md` (e.g., `auth-system.md`)
+**Template**: `templates/feature.md`
 
 ### Notes (`notes/`)
+
 Add notes when you discover:
+
 - API quirks or gotchas
 - Performance optimizations
 - Debugging techniques
 - Third-party service behaviors
+- Workarounds that aren't obvious from code
 
 **Format**: `topic-name.md` (e.g., `stripe-webhooks.md`)
+**Template**: `templates/note.md`
 
 ### Product (`product/`)
+
 Add product docs for:
+
 - User personas
 - User flows and journeys
 - Research findings
@@ -49,14 +85,29 @@ Add product docs for:
 
 **Format**: `document-name.md` (e.g., `personas.md`)
 
+## When to Prompt for Knowledge Capture
+
+Proactively suggest creating a knowledge doc when:
+
+- An architectural decision was made during implementation
+- A non-obvious workaround or debugging technique was discovered
+- A third-party API or integration behavior was learned through trial and error
+- A pattern was established that future work should follow
+- A significant feature was completed that spans multiple issues
+
+The `/knowledge` command provides a guided flow for creating docs.
+
 ## Always Update INDEX.md
 
-When adding any knowledge document, update `INDEX.md` so agents can discover it.
+When adding or modifying any knowledge document:
+
+1. Add or update the entry in `INDEX.md`
+2. Set the date to the current date (never leave as `YYYY-MM-DD`)
+3. Write a concise description that helps agents assess relevance without loading the full doc
 
 ## Relationship to Specs
 
-- **Specs** (in Linear) = What we're building now
+- **Specs** (in issue tracker) = What we're building now
 - **Knowledge** (here) = What we've learned that persists
 
 Specs reference knowledge. Knowledge grows from implementing specs.
-

package/template/flydocs/knowledge/templates/decision.md

@@ -0,0 +1,47 @@
+---
+id: NNN
+title: "[Decision title]"
+status: proposed | accepted | deprecated | superseded
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+supersededBy: null
+---
+
+# NNN — [Decision Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by NNN]
+
+## Context
+
+[What is the problem or situation that requires a decision? Include relevant constraints, requirements, and prior art.]
+
+## Decision
+
+[What was decided. Be specific — name the technology, pattern, or approach chosen.]
+
+## Alternatives Considered
+
+| Option          | Pros         | Cons                 |
+| --------------- | ------------ | -------------------- |
+| [Chosen option] | [Advantages] | [Tradeoffs accepted] |
+| [Alternative 1] | [Advantages] | [Why not chosen]     |
+| [Alternative 2] | [Advantages] | [Why not chosen]     |
+
+## Consequences
+
+**Positive:**
+
+- [Benefit 1]
+- [Benefit 2]
+
+**Negative / Tradeoffs:**
+
+- [Tradeoff 1]
+- [Tradeoff 2]
+
+**Follow-up actions:**
+
+- [Action needed as a result of this decision]

package/template/flydocs/knowledge/templates/feature.md

@@ -0,0 +1,35 @@
+---
+title: "[Feature name]"
+status: draft | current | deprecated
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+---
+
+# [Feature Name]
+
+## Overview
+
+[What this feature does and why it exists. 2-3 sentences.]
+
+## Architecture
+
+[How the feature is structured — key components, data flow, integration points.]
+
+## Key Files
+
+| File           | Purpose                        |
+| -------------- | ------------------------------ |
+| `path/to/file` | [What it does in this feature] |
+
+## Behaviors
+
+[Important behaviors, edge cases, or business rules that aren't obvious from code alone.]
+
+## Configuration
+
+[Any config, env vars, or feature flags that affect this feature.]
+
+## Related
+
+- [Links to related issues, decisions, or other knowledge docs]

package/template/flydocs/knowledge/templates/note.md

@@ -0,0 +1,25 @@
+---
+title: "[Note title]"
+category: discovery | gotcha | optimization | debugging | integration
+created: YYYY-MM-DD
+lastUpdated: YYYY-MM-DD
+relatedIssues: []
+---
+
+# [Note Title]
+
+## Summary
+
+[One-paragraph summary of the discovery, gotcha, or learning.]
+
+## Details
+
+[Full explanation. Include code examples, error messages, or configuration details as relevant.]
+
+## Impact
+
+[What this affects — which parts of the system, which workflows, which developers need to know.]
+
+## Resolution / Workaround
+
+[If applicable — what was done to address this, or how to work around it.]

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.5",
+  "version": "0.6.0-alpha.7",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",
 
@@ -45,6 +45,7 @@
         ".claude/commands/start-session.md",
         ".claude/commands/status.md",
         ".claude/commands/validate.md",
+        ".claude/commands/knowledge.md",
         ".claude/commands/wrap-session.md",
         ".claude/skills/README.md",
         ".cursor/hooks.json",
@@ -96,6 +97,9 @@
         "flydocs/knowledge/product/personas.md",
         "flydocs/knowledge/product/user-flows.md",
         "flydocs/README.md",
+        "flydocs/knowledge/templates/decision.md",
+        "flydocs/knowledge/templates/feature.md",
+        "flydocs/knowledge/templates/note.md",
         "flydocs/design-system/README.md",
         "flydocs/design-system/token-mapping.md",
         "flydocs/design-system/component-patterns.md"
@@ -125,6 +129,7 @@
           "flydocs-update.md",
           "flydocs-upgrade.md",
           "implement.md",
+          "knowledge.md",
           "new-project.md",
           "project-update.md",
           "refine.md",
@@ -177,7 +182,8 @@
         ],
         "knowledge": {
           "root": ["INDEX.md", "README.md"],
-          "product": ["personas.md", "user-flows.md"]
+          "product": ["personas.md", "user-flows.md"],
+          "templates": ["decision.md", "feature.md", "note.md"]
         }
       },
       "root": ["AGENTS.md", ".env.example"]