# Changelog

All notable changes to FlyDocs Core are documented here.

Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
Versioning: [Semantic Versioning](https://semver.org/).

---

## [0.8.1] — 2026-05-04

Same-day patch on top of 0.8.0. Adds two FlyDocs-authored optional
skills to the template tree and fixes a long-standing false-positive
in the PR-creation hook.

### Added

- **`human-writing` skill** (FLY-826) — prose quality skill (banned
  vocabulary, sentence-length variance, punctuation discipline,
  document formatting). Optional / opt-in via the workspace skill
  catalog.
- **`seo-aeo` skill** (FLY-826) — SEO + AI-answer-engine optimization
  for public web copy. Optional / opt-in. Pairs with a corresponding
  catalog entry in flydocs-app.

### Fixed

- **`post-pr-check` hook** false-positive on heredoc PR bodies. The
  hook now uses `shlex` to extract `--body` values instead of a
  non-greedy regex that truncated heredoc-quoted bodies and warned
  about missing `## Summary` / `## Test Plan` sections on every
  well-formed PR.

## [0.8.0] — 2026-05-04

Production launch release. Consolidates several pre-launch deprecations
and folds in the FLY-780/785/804 work that was code-bumped as `0.7.18`
but never published. Going forward, `1.0.0` is the next planned cut
once final launch follow-ups land.

### Added

- **Anonymous usage analytics** (FLY-780) — opt-out telemetry surfaced
  via a one-line disclosure on `flydocs init` completion. Disable with
  `flydocs telemetry disable` or `FLYDOCS_TELEMETRY=0`.
- **Tier-aware CTA** (FLY-819) — `printBetaCta()` accepts an optional
  tier. Local users see "Upgrade to cloud → `flydocs connect`"; cloud
  users see docs + Discord. `runLocalInit` now invokes the CTA (was
  missing).

### Deprecated

- **`flydocs install` command** (FLY-818) — use `flydocs init` instead.
  `install` now prints a deprecation notice and delegates to `init` for
  backward compatibility. Targeted for removal in a future major release.

### Changed

- **Credential storage standardized** (FLY-816) — `flydocs connect` and
  the legacy `flydocs install` now write `FLYDOCS_API_KEY` to
  `~/.flydocs/credentials` (the global path used by `flydocs init` and
  `flydocs auth`). Existing project `.env` entries continue to work via
  the legacy fallback in the auth resolution chain.
- **Setup consolidated into `/onboard`** (FLY-815) — `/flydocs-setup` is
  removed. `/onboard` now gates on whether `flydocs/context/project.md`
  has real content; for local tier it runs setup phases inline via IDE
  inference, for cloud tier it redirects to the workspace portal Get
  Started flow. SessionStart hook surfaces a non-blocking nudge when
  setup hasn't completed.
- **CLI launch polish** (FLY-814) — `flydocs sync` and `flydocs scan`
  short-circuit with friendly messages when invoked in a local-tier
  project instead of throwing "No API key found". `flydocs upgrade` no
  longer advertises the unimplemented `/flydocs-upgrade` "issue
  transfer" path.
- **Topology-aware integrity** (FLY-785) — integrity checks now respect
  multi-repo topology and skip workspace-only paths in single-repo
  installs.
- **Clear sentinels** (FLY-804) — sync-state and integrity sentinels
  now use explicit markers instead of derived defaults.

## [0.7.10] — 2026-04-22

### Fixed

- **Legacy workspace root config cleanup** (FLY-750) — sync now deletes
  the stale `.flydocs/config.json` at the workspace root in multi-repo
  workspaces after writing `workspace-config.json`. The legacy file had
  wrong tier, stale fields, and was never updated by sync.

### Deprecated

- **`flydocs sync` command** — use `flydocs update` instead. Sync is a
  subset of update; having both commands is confusing.

## [0.7.9] — 2026-04-22

### Changed

- **Config architecture audit** (FLY-725, ADR-011) — Establishes
  three-level config hierarchy (workspace > repo > global). Removes dead
  fields, simplifies `activeProjects` to singular `activeProjectId`,
  adds `repoDefaults` for per-repo issue creation defaults, writes
  workspace-level fields to `workspace-config.json` for multi-repo.

### Removed

- `defaultMilestoneId` — milestones should be explicit per-issue
- `provider.teamId` / `provider.teamName` — relay resolves server-side
- `topology.detectedVia` — never read by any consumer
- `version` in config body — use `.flydocs/version` file
- `add-active-project` / `remove-active-project` commands — singular project

## [0.7.8] — 2026-04-22

### Fixed

- **Sync/update workspace resolution** (FLY-741) — sync now reads
  workspaceId from local config.json first, matching the Python scripts'
  resolution order. Global credential is fallback only. Prevents
  cross-workspace contamination when the global credential points to a
  different workspace.
- **Init stops writing workspaceId to global credential** — workspaceId
  is per-project (stored in config.json). Writing it globally caused
  flydocs update in project A to pull config from whichever workspace
  was last initialized.

## [0.7.7] — 2026-04-21

### Fixed

- **Init workspace mismatch guard** (FLY-739) — `flydocs init` now warns
  when the target directory already has a config pointing at a different
  workspace. Requires explicit confirmation before overwriting. Prevents
  silent config contamination when using user-scoped API keys across
  multiple workspaces.

## [0.7.2] — 2026-04-20

### Added

- **CLI org selection for user-scoped keys** (FLY-733) — `flydocs init`
  detects user-scoped keys from `/auth/validate` response. Single org
  auto-selects; multiple orgs prompts before workspace selection. Selected
  orgId stored in global credentials.
- **`fetchOrgs` function** — calls new `/auth/orgs` endpoint.
- **`validateRelayKey` returns scope** — includes `scope` and `orgs` fields.
- **`GlobalCredential.orgId`** — stores selected org for user-scoped keys.

## [0.7.1] — 2026-04-19

Session lifecycle redesign (FLY-706, FLY-731, FLY-732). Moves session
start, issue fetching, and session wrap from aspirational skill
instructions into deterministic script commands.

### Added

- **`session.py start-context`** — single-call data gathering for
  `/start-session` and `/onboard`. Returns identity, workspace, active
  board/sprint, last session summary, active issue, and multi-repo
  sibling summaries as structured JSON.
- **`session.py list-issues`** — board-scoped issue fetch with automatic
  fallback. Reads config to determine active sprint/board, applies the
  correct filter, and retries without the filter if scoped query returns
  zero results.
- **`session.py wrap`** — deterministic session wrap. Writes
  `last-summary.json`, cleans up focus/status files, posts project
  update, and records graph session — all in one call.

### Changed

- **`/onboard` rewritten** — orientation only (project context, commands
  reference, setup validation). No longer fetches issues or shows a
  dashboard. Uses `start-context` for all data gathering.
- **`/start-session` rewritten** — uses `start-context` for data,
  `list-issues` for board-scoped fetch. Inline onboard gate eliminates
  the redirect loop (FLY-706). Procedure reduced from ~250 to ~100 lines.
- **`/wrap-session` rewritten** — uses `session.py wrap` for all file
  writes and cleanup. Model composes the summary; script does the I/O.
- **`session-start.py` hook** — removed eager `graph.json` O(n)
  iteration. Graph context is now lazy (queried on demand).
- **`prompt-submit.py` hook** — batched 3 git subprocess calls into
  single `git status --porcelain -b` (~100ms saved per prompt).
- **`stop-gate.py` hook** — IMPLEMENTING status now uses git-diff
  heuristic (like READY). Discussion/planning responses without code
  changes pass through without blocking.

### Fixed

- Start-session no longer redirects to `/onboard` which then tells user
  to run `/start-session` (redirect loop — FLY-706).
- Wrap-session now deterministically cleans up `focus.md`, `status`, and
  `acceptance-criteria.md` to prevent stale context in next session.

## [0.6.0] — 2026-04-13

First stable release of the 0.6 line. Rolls up Config v3 migration
(FLY-699, alphas 99-111) and multi-repo init/sync/update fixes
(FLY-707, alphas 112-113). Portal is the source of truth for cloud-tier
`project.md` and `service.json`.

### Highlights

- **Config v3** — server-driven config with envelope fields, script
  normalization, and multi-repo workspace sync
- **Multi-repo context pull** — per-repo `project.md` via X-Repo
  scoping, workspace rules + status workflow delivered in-band
- **Portal as source of truth** (cloud tier) — local context files
  are ephemeral, gitignored, regenerated on every init/update/sync

See alpha.112 and alpha.113 entries below for full fix details.

## [0.6.0-alpha.112] — 2026-04-13

Multi-repo init/sync/update fixes for cloud tier under FLY-707. Holds
the 0.6.0 stable cut until App's FLY-708 ships and end-to-end verification
passes on a real multi-repo workspace.

### Fixed

- **X-Repo scoping in sync/update** — `sync.ts` now passes `repoSlug` as
  the `X-Repo` header on every `/config/generate` call. Init already
  did this; sync and update did not, which meant every multi-repo
  child was asking the server for workspace-default content instead
  of its own per-repo content (FLY-707)
- **Multi-repo artifact redirect** — artifact writes correctly redirect
  to workspace root in multi-repo. Previously the redirect checked
  server-returned `topology` (a client-detected field the server never
  echoes), so the check silently failed and each child got its own full
  artifact sync (FLY-707)
- **Stray `flydocs/` at workspace root** — `sync.ts` no longer writes
  `flydocs/context/project.md` or `service.json` at workspace root in
  multi-repo; `update.ts` no longer calls the explicit context pull at
  workspace root. A one-time migration removes any existing stray
  `flydocs/context/` directory on next update (FLY-707)
- **`repoSlug` leak across child configs** — `sync.ts` always prefers
  the git-derived slug over the server echo. Pre-FLY-708 the server
  returns the first-row repo for every request, which was leaking into
  every child's config (e.g. `ditto-core` identifying as `flock-web`).
  `init.ts` also flipped to git-first precedence (FLY-707)
- **Silent `pullProjectContext` errors** — the helper now returns a
  structured result and `update.ts` surfaces success/failure
  explicitly. Previously the `try/catch` wrapper swallowed all errors,
  so there was no way to tell whether the pull actually ran (FLY-707)

### Added

- **X-Repo safety warning** — sync logs a warning when a multi-repo
  child can't resolve its own git remote, since that disables per-repo
  scoping entirely (FLY-707)
- **Cloud-tier gate on context overwrite** — "always overwrite"
  behavior for `project.md` / `service.json` is strictly gated behind
  `tier === "cloud"`. Local tier users retain ownership of their
  files (FLY-707)
- **Per-repo status line on update** — each multi-repo child now
  prints `Pulled project context for <repo> (from portal)` on
  successful pull (FLY-707)

### Internal

- `resolveRepoSlugFromGit` moved from `init.ts` to `src/lib/workspace.ts`
  (shared helper for init + sync paths)
- `resolveArtifactWriteRoot` removed from `sync.ts` — redirect is now
  inline, gated by `parent has .flydocs-workspace.json` (more reliable
  than topology check)

### Known Follow-ups (Post-FLY-708)

- FLY-708 (App) — adds per-repo `context` field to `/config/generate`
  response, enabling in-band content delivery without a second
  `context.py pull` round-trip. Target staging 2026-04-17
- FLY-710 (Core) — drops `context.py push`, section-merge, and
  workflow-text injection once FLY-708 is live. Portal becomes single
  source of truth for cloud-tier `project.md`

## [0.6.0-alpha.45] — 2026-04-04

### Changed

- **Config.json gitignored** — `.flydocs/config.json` is now server-managed,
  pulled fresh on every init/sync. Version file and manifest.json reads
  removed (FLY-609)
- **Issue templates scaffolded on init** — `.flydocs/templates/` copied from
  bundled template on first init, then left alone (FLY-610)
- **Git migration cleanup** — sync detects and untracks committed copies of
  server-managed files from old PR-based flow (FLY-611)

## [0.6.0-alpha.44] — 2026-04-04

### Fixed

- **Multi-repo clone flow** — Artifacts now sync to workspace root, not
  each child repo (FLY-602)
- **post-transition-check hook** — Session files resolve to active child
  repo in sibling-repos topology (FLY-601)
- **identity.name fallback** — workspace.py get-me reads `name` with
  `displayName` fallback to match API contract (FLY-601)
- **Stale references** — graph_query flag, status names, script names
  fixed across commands and stage files (FLY-605)

### Changed

- **Server-managed context files** — project.md and service.json are now
  gitignored, overwritten from server on every init/sync. Portal is
  source of truth. pushContext relay client added (FLY-597)
- **UX overhaul for /onboard and /start-session** — Conversational flow,
  no config field names exposed, interactive project selection, workspace
  name display, placeholder project.md detection with guided setup (FLY-600)
- **SKILL.md and CLAUDE.md** — Added audit/fix to issues.py table,
  post-pr-check to hook table (FLY-606)

## [0.6.0-alpha.43] — 2026-04-03

### Changed

- **UX overhaul for /onboard and /start-session** — Conversational flow,
  no config field names exposed, interactive project selection, workspace
  name display, placeholder project.md detection with guided setup (FLY-600)

## [0.6.0-alpha.36] — 2026-04-03

### Added

- **Hook CWD resolution for sibling-repos** — Hooks detect the active child
  repo and read config/session from the correct directory. Shared
  `repo_context.py` module with file-path detection (Option A) and
  active-repo pointer fallback (Option B) (FLY-586)
- **Auto-approve regex for parent paths** — Scripts invoked via `../` from
  child repos now auto-approved in sibling-repos topology (FLY-587)
- **Workspace session aggregation** — Session-start hook aggregates issues,
  active work, and blockers across all child repos. Shows per-repo active
  issues with status annotations (FLY-588)
- **Graph-based session continuity** — Session-start hook reads the most
  recent session node from the context graph for richer cross-session
  handoff alongside `last-summary.json` (FLY-585)
- **Cross-repo context graph** — `graph_build.py --workspace` aggregates
  child repo graphs with repo-prefixed session nodes and cross-repo
  dependency edges from service descriptors. `graph_query.py --workspace`
  and `graph_session.py --workspace` support workspace-level operations
  (FLY-590)

## [0.6.0-alpha.32] — 2026-04-02

### Added

- **Server-managed artifact sync** — Init and sync fetch skills, hooks,
  commands, agents, and IDE configs from relay API with incremental versioning
  via `artifactVersion` (FLY-567)
- **`flydocs scan` command** — Trigger server-side AI scanning to generate
  `project.md` and `service.json`. Admin-only with spinner UX. Also available
  as `flydocs init --scan` (FLY-568)
- **Init scan auto-detection** — When no generated context exists, admins are
  prompted to scan; non-admins get guidance to contact their admin (FLY-569)
- **IDE config archiving** — Existing `.cursorrules`, `.claude/CLAUDE.md`, and
  `.cursor/rules/` are backed up to `flydocs/knowledge/archived/` before
  server-managed files overwrite them (FLY-570)
- **Topology-adaptive writes** — Multi-repo workspaces write artifacts to the
  workspace parent; child repos only get context files. Includes migration
  cleanup of server-managed files from prior single-repo setups (FLY-571)
- **Expanded gitignore** — Server-managed paths (`.claude/skills/`, `commands/`,
  `hooks/`, `agents/`, `settings.json`, `CLAUDE.md`, `.cursor/rules/`,
  `.cursor/commands/`, `AGENTS.md`) now gitignored. Sync updates existing
  gitignore files (FLY-572)

### Changed

- **Contract updates** — Added `artifactVersion` to config/generate and
  config/check responses. Added `role` to identity block. New artifact and
  scan response types aligned with App relay endpoints.

---

## [0.6.0-alpha.24] — 2026-03-30

### Added

- **Auto-resolve provider identity** — `workspace.py validate` now attempts
  `GET /auth/me` before requiring manual `set-identity` step. If the relay
  returns a provider identity, `me.json` is written automatically (FLY-520)

### Changed

- **Friendlier identity fallback** — when auto-resolve fails, the validation
  message now points to the dashboard profile page instead of showing a raw
  script command

---

## [0.6.0-alpha.23] — 2026-03-29

### Changed

- **CLAUDE.md** — scoped skill-led reasoning to workflow operations only; general
  coding no longer triggers skill file reads (FLY-450)
- **AGENTS.md** — added exact script commands to Automatic Workflow Behavior section
  for deterministic issue transitions (FLY-450)

---

## [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

- **Banner copy** — title changed from "FlyDocs Core" to "FlyDocs (Beta)",
  subtitle changed to "Spec-Driven Context That Helps Engineers Fly"
- **Beta CTA** — "priority support" replaced with "web portal", URL now
  renders as clickable `flydocs.ai` hyperlink via OSC 8 terminal escape

---

## [0.5.0-beta.8] — 2026-02-22

### Added

- **Context7 documentation skill** (`flydocs-context7`) — stdlib-only Python script
  that calls the Context7 REST API to fetch up-to-date library documentation.
  Replaces the removed Context7 MCP with a skill+script pattern.
  - `context7.py search <library> [query]` — resolve library name to Context7 ID
  - `context7.py docs <library_id> <query>` — fetch relevant documentation snippets
  - Works without API key (anonymous, ~1,000 calls/month); optional
    `CONTEXT7_API_KEY` in `.env` for higher rate limits
  - Auto-approved by hook for seamless agent invocation
  - Cursor rule included for cross-IDE support
- **Context7 API key** in `.env.example` — optional configuration for higher rate limits

### Fixed

- `.env.example` — corrected "Figma MCP" reference to "flydocs-figma skill"

## [0.5.0-beta.7] — 2026-02-22

### Removed

- **All MCP references** — removed `.cursor/mcp.json`, `prefer-scripts.py` hook,
  MCP config preservation in update flow, MCP section in instructions template.
  Skills fully replace MCPs as the FlyDocs architecture.
- **Phantom skills** — removed references to `implementation-flow`, `review-workflow`,
  `spec-templates` skills that were never shipped.

### Fixed

- **Command injection** (`connect.ts`) — replaced `execSync` subprocess with native
  `fetch()` for Linear API key validation.
- **Version comparison** — pre-release versions (e.g. `0.5.0-beta.3`) now compare
  correctly instead of returning NaN.
- **Auto-approve hook** — tightened regex to anchor script paths, preventing potential
  pattern-matching bypasses.
- **Post-edit hook** — added path traversal validation using `os.path.realpath()`.
- **Post-install scripts** — switched from `execSync` to `execFileSync` for subprocess safety.

### Changed

- **Stack detection** — now reads `flydocs/context/project.md` in addition to
  `package.json` for declared stack frameworks.
- **Community skills on update** — filters already-installed skills before prompting.
- **Cloud exposure** — `.env.example` marked as cloud tier only, `flydocs/README.md`
  rewritten as tier-generic, config defaults changed to `tier: "local"`.
- **Deprecated cleanup** — `.cursor/mcp.json` and `prefer-scripts.py` added to
  deprecated files list for automatic cleanup on update.

---

## [0.4.0] — 2026-02-18

### Added

- **Context Graph skill** (`flydocs-context-graph`) — relationship-aware knowledge
  graph that connects skills, ADRs, issues, modules, and sessions. Implemented as
  ADR-006 across five phases:
  - `graph_build.py` — scans skills and ADRs, extracts cross-references, produces
    `flydocs/context/graph.json`. Manual nodes/edges preserved on rebuild.
  - `graph_query.py` — BFS traversal with depth, relationship type, and direction
    filters. Outputs compressed markdown or JSON.
  - `graph_update.py` — incremental add/remove for nodes and edges.
  - `graph_context.py` — assembles compressed context block (~200-400 tokens) for
    the prime hook given active issue and git branch.
  - `graph_session.py` — records session outcomes as graph nodes with WORKED_ON
    and PRODUCED edges for cross-session continuity.
- **Automatic context injection** — `prompt-submit.py` hook now calls `graph_context.py`
  every prompt. Agents receive a temporal anchor (current date) and related decisions,
  skills, and prior session summaries without any manual effort.
- **Skill ordering in manifest** — `generate_manifest.py` reads PRECEDES edges from
  the graph and adds a "Loads After" column to the skills index table.
- **Install-time graph generation** — both fresh install and update paths call
  `graph_build.py` after skill installation. Every FlyDocs project gets a context
  graph automatically.

### Changed

- **Session wrap procedure** — `session.md` now includes a step to record session
  outcomes in the context graph via `graph_session.py`. Skips silently if not installed.
- **Session staleness policy** — session nodes within 7 days get full weight, linear
  decay to 30 days, then excluded from context.

### Migration

- **`.gitignore` update** — `flydocs/context/graph.json` is automatically added to
  `.gitignore` during update if missing. The graph is gitignored because it contains
  session-specific data and can be rebuilt from sources.

---

## [0.3.10] — 2026-02-17

### Fixed

- **API null data crash** (FLY-178) — `flydocs_api.py` now normalizes `null` data
  responses to empty dict before returning. Fixes `AttributeError` crashes in all
  20+ scripts when Linear returns API errors. `create_issue.py` also retries without
  labels when label IDs are rejected (stale config after team migration).
- **`assign_milestone.py` flag parsing** (FLY-179) — rewritten with argparse.
  Now supports both positional (`assign_milestone.py REF UUID`) and flag
  (`--milestone UUID`) syntax. Previously `--milestone` was captured as the
  milestone ID value.
- **`list_milestones.py` missing fields** (FLY-180) — GraphQL query now includes
  `sortOrder` and `project { id name }`. Output sorted by project then sortOrder.
- **Community skills recommendation UI** (FLY-48) — rendering artifacts resolved
  by the `prompt_community_skills()` rewrite in 0.3.9.

---

## [0.3.9] — 2026-02-17

### Added

- **Skill search and install CLI** (ENG-443) — `flydocs skills` subcommand with
  `search`, `add`, `remove`, and `list` operations. Search the curated community
  skills catalog, install from known names or GitHub repo references, and manage
  installed skills post-install. Platform skills (`flydocs-*`) are guarded from
  modification. Installs validate SKILL.md frontmatter, copy cursor rules, update
  config, and regenerate the skill manifest automatically.
- **Install.sh skill discovery update** (ENG-445) — community skill installation
  now delegates to `skill_manager.py` (full directory download with validation)
  instead of single-file curl. Added `--yes`/`-y` flag for non-interactive mode.
  Enhanced stack detection: tsconfig.json (TypeScript), vitest, jest, testing-library.

---

## [0.3.8] — 2026-02-14

### Added

- **`create_issue.py --description-file` and stdin** — both cloud and local tiers now
  accept `--description-file PATH` or piped stdin for issue descriptions. Eliminates
  the two-step create + update_description workaround for long descriptions.
- **`update_issue.py --title`** — cloud tier bulk update script now supports renaming
  issues via `--title "new title"`.

---

## [0.3.7] — 2026-02-11

### Added

- **Skill manifest generator** (ENG-442) — `generate_manifest.py` scans SKILL.md
  frontmatter and produces a compressed skills index table. Injected into CLAUDE.md
  and AGENTS.md between `<!-- flydocs:skills-manifest -->` markers. Bridges skill
  discovery with on-demand retrieval — agents see triggers in always-loaded context.
- **`.flydocs/scripts/` owned directory** — shared utility scripts (not mechanism
  scripts) now have a dedicated home, managed by manifest.json ownership.

---

## [0.3.6] — 2026-02-10

### Added

- **Milestone, project, and dueDate in issue output** — `list_issues.py` now returns
  `milestone`, `milestoneId`, `milestoneSortOrder`, `project`, `projectId`, and `dueDate`
  for every issue. `get_issue.py` returns the same fields (minus `milestoneSortOrder`).
  Enables milestone-grouped dashboards and priority-based session planning.

### Changed

- **Session start workflow rewritten** — `session.md` now instructs agents to group issues
  by milestone (in milestone order), identify the current milestone, suggest a starting point
  based on priority cascade (blocked → in-progress → due soon → highest priority in current
  milestone), and surface other product issues separately. Never shows issues outside
  the product scope.

### Fixed

- **`create_milestone.py` missing projectId** — `ProjectMilestoneCreateInput` requires a
  `projectId`. Script now defaults to first `activeProject` from config, with `--project`
  flag to override.

---

## [0.3.5] — 2026-02-10

### Added

- **`list_projects.py` product scope** (ENG-475) — now respects `workspace.activeProjects`
  config. `--all` bypasses product scope to show all team projects.

### Fixed

- **`list_projects.py` 400 error** (ENG-474) — state filter was using nested
  `{type: {nin: [...]}}` instead of direct `StringComparator` `{nin: [...]}`.
  Both `--active` (started only) and default (excludes completed/canceled) now work.
- **`list_projects.py --active`** — now correctly filters to only `started` projects
  instead of being a no-op duplicate of the default behavior.
- **`assign_milestone.py` error handling** — null-safe check on API response prevents
  `AttributeError` when GraphQL returns errors.

---

## [0.3.4] — 2026-02-10

### Added

- **`list_issues.py --milestone` filter** — filter issues by project milestone ID.
  Get milestone IDs from `list_milestones.py`, then pass to `list_issues.py --milestone <ID>`
  to see all issues within a specific milestone.

---

## [0.3.3] — 2026-02-10

### Fixed

- **Shell escaping in `update_description.py`** — descriptions with apostrophes,
  parentheses, quotes, and other shell metacharacters no longer break when passed
  via `--text`. Scripts now accept stdin as input, allowing safe heredoc piping:
  `python3 update_description.py ENG-123 <<'EOF'`
- **Shell escaping in `comment.py`** — same stdin fallback added. Comment body
  argument is now optional when piping via stdin.

---

## [0.3.2] — 2026-02-09

### Fixed

- **API connection reliability** — reduced socket timeout from 30s to 10s and increased
  max retries from 3 to 5. Resolves intermittent hangs caused by DNS returning unreachable
  Cloudflare edge IPs. Scripts now fail over to a working IP within seconds instead of
  waiting 10-30s per attempt.
- **TimeoutError handling** — retry loop now catches `TimeoutError` in addition to
  `URLError`, preventing unhandled socket timeouts from crashing scripts.

---

## [0.3.1] — 2026-02-08

### Fixed

- **`list_issues.py` product scope** — scoping via `activeProjects` and `product.labelIds`
  now applies regardless of `--active` or `--status` flags. Previously, these flags
  bypassed product scope entirely, returning all team issues.

### Added

- **`build_product_scope()` API helper** — new method on `FlyDocsClient` implements the
  product scope cascade: `activeProjects` → `product.labelIds` → team-wide.
- **Multiple `activeProjects` support** — `list_issues.py` now uses OR logic when
  multiple active projects are configured (was only using the first one).
- **Product label AND filtering** — when `product.labelIds` is set and no `activeProjects`
  are configured, issues must have ALL specified labels to be included.

---

## [0.3.0] — 2026-02-08

### Added

- **`update_issue.py` bulk update script** — set multiple fields (priority, estimate,
  assignee, state, description, comment) in a single API call instead of separate scripts.
- **`list_issues.py --active` flag** — returns all non-terminal issues (excludes Done,
  Archived, Canceled, Duplicate). Replaces `status_summary.py`.
- **`list_issues.py` multi-status support** — comma-separated: `--status READY,IMPLEMENTING,BLOCKED`
- **`get_issue.py --fields` flag** — `basic` skips comment fetch for faster responses,
  `full` includes comments (default).
- **In-process API caching** — issue ID resolution, team members, and active cycle
  cached within each script invocation to reduce redundant API calls.

### Changed

- **`transition.py` optimized** — combined state update and cycle assignment into a
  single `issueUpdate` mutation (was two separate calls for IMPLEMENTING transitions).
- **Session start efficiency** — single `list_issues.py --active` call replaces
  per-status queries. Issues grouped by status in response.

### Removed

- **`status_summary.py`** — retired from cloud mechanism. Use `list_issues.py --active`
  and group results by the status field instead.

---

## [0.2.1] — 2026-02-07

### Fixed

- **Commands not fully populating** — changed from additive `cp` to clear-then-copy
  for `.claude/commands/` and `.cursor/commands/` directories.
- **`docflow-core.mdc` not cleaned up** — added to deprecated cursor rules list.
- **Config version not set on fresh install** — fresh install path now sets version
  in `config.json`.
- **Template config version mismatch** — template `config.json` was `0.1.0`, now
  synced with version file.

### Added

- **`--force` flag** — force update even when versions match.
- **Old cursor rule directories and commands** added to deprecated cleanup.

---

## [0.2.0] — 2026-02-06

### Added

- **Scenario-aware setup command** — `/flydocs-setup` rewritten as a comprehensive
  agent prompt handling three scenarios: New Project, DocFlow Migration, FlyDocs Update.
  Includes proactive repo scanning for PRDs and existing documentation.
- **Changelog and version tracking** — `CHANGELOG.md` included in every install.
  `install.sh --update` now displays what changed between your version and the new one.
- **Legacy context migration** — `install.sh` safely moves pre-v1.0 separate context
  files (`overview.md`, `stack.md`, `standards.md`) to a `legacy/` folder. The setup
  command reads from legacy, consolidates into `project.md`, and cleans up.
- **Deprecated file cleanup** — `install.sh --update` detects and offers to remove
  pre-v1.0 artifacts: old skills, rules, hooks, and cursor rules.

### Changed

- **Version file synced with manifest** — `.flydocs/version` now matches
  `manifest.json` version field (was out of sync in 0.1.0).

### Removed

- Orphaned hook scripts: `session-end.py`, `linear-auto-approve.py`

---

## [0.1.0] — 2026-01-15

### Added

- Initial release of FlyDocs Core
- Workflow skill (`flydocs-workflow`) with full lifecycle stages
- Mechanism skills: `flydocs-cloud` (Linear API) and `flydocs-local` (file-based)
- Premium skills: `flydocs-figma`, `flydocs-estimates`
- Agent definitions: PM, Implementation, Review, Research
- 16 slash commands for the full development workflow
- Hook scripts: auto-approve, prefer-scripts, post-edit, prompt-submit
- Issue templates: feature, bug, chore, idea
- Community skill suggestions based on detected stack
- `install.sh` with fresh install and update modes
- Remote installation via GitHub App token