@flydocs/cli 0.5.0-beta.9 → 0.6.0-alpha.10

package/template/.flydocs/config.json

@@ -1,18 +1,16 @@
 {
-  "version": "0.5.0-beta.9",
+  "version": "0.6.0-alpha.10",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,
+  "workspaceId": null,
   "paths": {
     "content": "flydocs"
   },
-  "provider": {
-    "type": null,
-    "teamId": null
-  },
   "workspace": {
     "activeProjects": [],
     "defaultMilestoneId": null,
+    "repoSlug": null,
     "product": {
       "name": null,
       "labelIds": [],
@@ -21,7 +19,7 @@
     }
   },
   "issueLabels": {
-    "_note": "Run /flydocs-setup to populate these from your Linear team",
+    "_note": "Run /flydocs-setup to populate these from your workspace",
     "category": {
       "feature": null,
       "bug": null,
@@ -50,18 +48,6 @@
     "installed": [],
     "custom": []
   },
-  "statusMapping": {
-    "BACKLOG": "Backlog",
-    "READY": "Todo",
-    "IMPLEMENTING": "In Progress",
-    "BLOCKED": "Blocked",
-    "REVIEW": "In Review",
-    "TESTING": "QA",
-    "COMPLETE": "Done",
-    "ARCHIVED": "Archived",
-    "CANCELED": "Canceled",
-    "DUPLICATE": "Duplicate"
-  },
   "designSystem": null,
   "aiLabor": {
     "enabled": false,

package/template/.flydocs/hooks/prompt-submit.py

@@ -168,15 +168,38 @@ def get_flydocs_version() -> str | None:
 
 
 def get_setup_nudge() -> str | None:
-    """Check if setup has been completed, return nudge if not."""
+    """Check if setup has been completed, return nudge if not.
+
+    Reads validation cache (written by validate_setup.py) for specific
+    missing items. Falls back to generic nudge if cache is absent.
+    """
     config_file = Path('.flydocs/config.json')
     if not config_file.exists():
         return None
     try:
         config = json.loads(config_file.read_text())
-        # Only nudge if field is explicitly set to false (not missing)
-        if 'setupComplete' in config and config['setupComplete'] is False:
-            return '[Setup incomplete — run /flydocs-setup to configure your project]'
+        if config.get('setupComplete') is not False:
+            return None
+
+        # Check validation cache for specific missing items
+        cache_file = Path('.flydocs/validation-cache.json')
+        if cache_file.exists():
+            try:
+                cache = json.loads(cache_file.read_text())
+                missing = cache.get('missing', [])
+                warnings = cache.get('warnings', [])
+                parts = []
+                if missing:
+                    parts.append(f'missing: {", ".join(missing)}')
+                if warnings:
+                    parts.append(f'warnings: {", ".join(warnings)}')
+                if parts:
+                    detail = '; '.join(parts)
+                    return f'[Setup incomplete — {detail}. Run /flydocs-setup or fix in dashboard]'
+            except (json.JSONDecodeError, OSError, IOError):
+                pass
+
+        return '[Setup incomplete — run /flydocs-setup to configure your project]'
     except (json.JSONDecodeError, OSError, IOError):
         pass
     return None

package/template/.flydocs/version

@@ -1 +1 @@
-0.5.0-beta.9
+0.6.0-alpha.10

package/template/AGENTS.md

@@ -92,14 +92,14 @@ Follow these rules in every response for consistent, scannable output.
 IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
 Consult the relevant skill BEFORE writing code or making workflow decisions.
 
-| Skill             | Triggers                                                                                                                | Entry                                     |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md     |
-| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                               | .claude/skills/flydocs-context7/SKILL.md  |
-| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                   | .claude/skills/flydocs-estimates/SKILL.md |
-| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                           | .claude/skills/flydocs-figma/SKILL.md     |
-| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                       | .claude/skills/flydocs-local/SKILL.md     |
-| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue             | .claude/skills/flydocs-workflow/SKILL.md  |
+| Skill             | Triggers                                                                                                                                           | Entry                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, cloud                                    | .claude/skills/flydocs-cloud/SKILL.md     |
+| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                                                          | .claude/skills/flydocs-context7/SKILL.md  |
+| flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                                              | .claude/skills/flydocs-estimates/SKILL.md |
+| flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                                                      | .claude/skills/flydocs-figma/SKILL.md     |
+| flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                                                  | .claude/skills/flydocs-local/SKILL.md     |
+| flydocs-workflow  | capture, refine, activate, implement, review, validate, close, session, workflow, transition, status, issue, knowledge, document, PR, pull request | .claude/skills/flydocs-workflow/SKILL.md  |
 
 <!-- flydocs:skills-manifest:end -->
 

package/template/CHANGELOG.md

@@ -7,6 +7,189 @@ Versioning: [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.6.0-alpha.4] — 2026-03-13
+
+### Added
+
+- **Status mapping** — new `list_statuses.py` and `set_status_mapping.py`
+  scripts. Setup flow auto-maps provider workflow states to FlyDocs statuses
+  after label config, warns on unmapped statuses without blocking.
+
+---
+
+## [0.6.0-alpha.3] — 2026-03-13
+
+### Added
+
+- **Provider selection** — new `list_providers.py` and `set_provider.py`
+  scripts for multi-provider support (Linear + Jira). Setup flow detects
+  connected providers before team selection.
+- **Inline API key prompt** — `flydocs install` now prompts for FlyDocs API
+  key when cloud tier is selected. No separate `flydocs connect` step needed.
+- **Existing config detection** — install detects pre-existing `.claude/CLAUDE.md`,
+  `settings.json`, `hooks.json`, and `AGENTS.md`. Prompts user to overwrite
+  (with backup) or preserve.
+- **`--project` flag** — `create_issue.py` accepts `--project <id>` to scope
+  issues to a specific project. Fixes milestone/project mismatch during setup.
+- **Team creation** — `create_team.py` with `--parent` flag for sub-teams.
+
+### Changed
+
+- **Setup flow restructured** — Phase 2 now starts with provider detection,
+  then team selection, project, labels. Milestones and issues pass `--project`.
+- **Community skill output** — install shows one line per skill instead of
+  4-5 verbose lines. "No triggers" warning suppressed for community skills.
+- **`/flydocs-upgrade` streamlined** — Phase 1 inlines API key handling
+  instead of requiring a separate terminal step.
+- **API key helpers extracted** — shared `api-key.ts` module used by both
+  `install` and `connect` commands.
+
+---
+
+## [0.6.0-alpha.1] — 2026-03-12
+
+### Added
+
+- **Cloud relay scripts** — all cloud mechanism scripts rewritten as thin REST
+  wrappers calling the FlyDocs Relay API (`app.flydocs.ai/api/relay`). Provider
+  translation (Linear, Jira) happens server-side.
+- **Team discovery** — new `list_teams.py` and `set_team.py` scripts for
+  discovering available teams and storing team preference on the relay.
+- **Label configuration** — new `list_labels.py` and `set_labels.py` scripts
+  for server-side label resolution. Labels are configured per API key with
+  defaults and type-to-label mapping.
+- **`--labels` flag** — `create_issue.py` and `update_issue.py` now accept
+  optional `--labels "name1,name2"` for ad-hoc labels alongside the `type` field.
+- **Cloud tier install** — `flydocs install` supports tier selection (local/cloud).
+  Cloud installs the relay mechanism skill and premium skills.
+- **`flydocs connect`** — new command to validate and store `fdk_` API keys.
+- **`/flydocs-upgrade`** — upgrade from local to cloud tier.
+- **Alpha dist-tag** — `-alpha.x` versions publish to npm `alpha` dist-tag.
+
+### Changed
+
+- **Setup flow updated** — `/flydocs-setup` Phase 2 now uses `list_teams.py`
+  for team discovery, `set_team.py` for selection, and `list_labels.py` +
+  `set_labels.py` for label configuration with auto-detection.
+- **API key reference** — setup instructions now reference `FLYDOCS_API_KEY`
+  instead of `LINEAR_API_KEY`.
+- **Relay URL** — `app.flydocs.ai/api/relay` (same Vercel deployment, no
+  separate API domain). Override with `FLYDOCS_RELAY_URL` env var.
+
+---
+
+## [0.5.0-beta.19] — 2026-02-27
+
+### Fixed
+
+- **Install always confirms before proceeding** — the "Install FlyDocs here?"
+  prompt now shows even when an existing config is detected. Previously, reinstalls
+  with an existing `.flydocs/config.json` skipped the confirmation entirely.
+
+---
+
+## [0.5.0-beta.18] — 2026-02-27
+
+### Changed
+
+- **Telemetry disabled by default** — analytics are opt-in only. No data is sent
+  until a user explicitly runs `flydocs telemetry enable`. Removed first-run notice.
+
+---
+
+## [0.5.0-beta.17] — 2026-02-26
+
+### Added
+
+- **Anonymous usage analytics** — opt-in PostHog telemetry tracks install/update
+  funnel events (started, tier selected, completed). No personal data or code
+  collected. Opt out with `flydocs telemetry disable` or `FLYDOCS_TELEMETRY=0`.
+- **`flydocs telemetry` command** — `enable`, `disable`, `status` subcommands
+  for managing anonymous analytics.
+- **`flydocs uninstall` command** — cleanly removes FlyDocs from a project.
+  Interactive mode prompts to archive or delete user content. Supports `--force`,
+  `--all`, `--yes`, `--here`, `--path` flags. Preserves community skills and `.env`.
+
+---
+
+## [0.5.0-beta.16] — 2026-02-24
+
+### Changed
+
+- **Premium skills are cloud-only** — `flydocs-figma` and `flydocs-estimates` are no
+  longer installed on local tier. Existing local installs have them cleaned up on
+  next update. Core skills (workflow, context-graph, context7) remain on all tiers.
+
+---
+
+## [0.5.0-beta.15] — 2026-02-24
+
+### Changed
+
+- **CTA links use full URLs** — Discord and flydocs.ai links now display as full URLs
+  (`https://discord.com/invite/...`, `https://www.flydocs.ai`) for terminal compatibility.
+  Discord section shows "Join the Discord" heading with invite link on its own line.
+  Setup command CTA updated to match.
+
+---
+
+## [0.5.0-beta.14] — 2026-02-24
+
+### Changed
+
+- **Discord CTA restyled** — "Join the Discord" is now a bold cyan clickable hyperlink
+  with descriptive copy ("for upcoming features, support, and early access to what's
+  next"), matching the docs page CTA style. "flydocs.ai" link also bold cyan and clickable.
+
+---
+
+## [0.5.0-beta.13] — 2026-02-24
+
+### Changed
+
+- **New ASCII banner** — gradient block-letter "FlyDocs" heading with subtle drop shadow,
+  replacing the block mark logo. Pink-to-purple gradient matches brand colors using true
+  color (24-bit) escape sequences. Tagline in bold white, version label in dim.
+
+---
+
+## [0.5.0-beta.12] — 2026-02-24
+
+### Changed
+
+- **Optional sub-agents** — sub-agents (PM, implementation, review, research) are now
+  an opt-in prompt during install and update. Recommended but not required. Existing
+  installs are silently updated on next `flydocs update`.
+- **Removed hardcoded model selections** — Claude Code agent files no longer specify
+  `model: opus` or `model: sonnet`. Agents inherit the user's configured model,
+  matching the Cursor agent behavior.
+- **CLI copy alignment** — banner tagline updated to "Structured context for AI coding
+  tools", beta CTA refocused on Discord community, docs references point to flydocs.ai.
+- **Setup command CTA** — updated to show community links (Discord, flydocs.ai) and
+  upcoming features instead of "join the beta" messaging.
+
+---
+
+## [0.5.0-beta.11] — 2026-02-23
+
+### Fixed
+
+- **Beta CTA hyperlink** — fixed OSC 8 escape sequence (BEL terminator, color inside
+  hyperlink wrapper). Display text changed to `https://www.flydocs.ai` for terminals
+  that don't support clickable links. UTM tracking preserved in the link target.
+
+---
+
+## [0.5.0-beta.10] — 2026-02-22
+
+### Fixed
+
+- **`.env.example` not updating** — reclassified from `template_files` to `owned_files`
+  in manifest. Now overwritten on update so new config entries (like `CONTEXT7_API_KEY`)
+  and copy fixes propagate to existing installations.
+
+---
+
 ## [0.5.0-beta.9] — 2026-02-22
 
 ### Changed

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.]