@flydocs/cli 0.6.0-alpha.13 → 0.6.0-alpha.20

package/template/.claude/settings.json

@@ -2,11 +2,11 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|Edit|Write",
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/auto-approve.py",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-approve.py",
             "timeout": 5
           }
         ]
@@ -18,10 +18,25 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/post-edit.py",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit.py",
             "timeout": 30
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-pr-check.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-transition-check.py",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -29,7 +44,29 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.flydocs/hooks/prompt-submit.py",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/prompt-submit.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-gate.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.py",
             "timeout": 10
           }
         ]

package/template/.claude/skills/README.md

@@ -11,16 +11,12 @@
 Owned and maintained by FlyDocs. May include executable scripts and premium
 functionality gated via API relay.
 
-| Skill               | Category         | Purpose                                                 |
-| ------------------- | ---------------- | ------------------------------------------------------- |
-| `flydocs-workflow`  | Core             | Lifecycle stages, session management, comment templates |
-| `flydocs-local`     | Mechanism (free) | File-based issue management                             |
-| `flydocs-cloud`     | Mechanism (paid) | Linear/provider issue management via API                |
-| `flydocs-context7`  | Core             | Library documentation lookup via Context7 API           |
-| `flydocs-figma`     | Premium          | Design extraction from Figma                            |
-| `flydocs-estimates` | Premium          | AI token/labor cost estimation                          |
+| Skill              | Purpose                                                                      |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `flydocs-workflow` | Unified skill — lifecycle, issues, projects, Figma, estimates, context graph |
 
-Only one mechanism skill is active at a time. Determined by `tier` in `.flydocs/config.json`.
+All functionality consolidated into a single skill. Tier (local vs cloud) is
+auto-detected from `.flydocs/config.json` — no separate mechanism skills.
 
 ### Unprefixed — Community Skills
 
@@ -101,8 +97,8 @@ The body serves as a **compressed index** — not a documentation dump. Target ~
 ```markdown
 # Skill Name
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
-[domain]. Read the relevant section before acting.
+Use this skill when performing [domain]-specific operations.
+For general coding, skip this — just write code.
 
 ## Key Rules (always apply)
 
@@ -191,12 +187,13 @@ CLAUDE.md and AGENTS.md between markers:
 
 ## Skills Index
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning.
+Consult the workflow skill for **issue operations and status transitions only**.
+For general coding tasks, skip this — just write code.
 
-| Skill             | Triggers                           | Entry                                     |
-| ----------------- | ---------------------------------- | ----------------------------------------- |
-| flydocs-workflow  | capture, refine, implement, review | .claude/skills/flydocs-workflow/SKILL.md  |
-| typescript-strict | TypeScript, type error, any type   | .claude/skills/typescript-strict/SKILL.md |
+| Skill             | Triggers                                      | Entry                                     |
+| ----------------- | --------------------------------------------- | ----------------------------------------- |
+| flydocs-workflow  | create issue, transition, assign, close issue | .claude/skills/flydocs-workflow/SKILL.md  |
+| typescript-strict | TypeScript, type error, any type              | .claude/skills/typescript-strict/SKILL.md |
 
 <!-- flydocs:skills-manifest:end -->
 ```
@@ -257,17 +254,18 @@ For detailed patterns, see `reference/patterns.md`.
 
 ---
 
-## Mechanism Contract
+## Unified Dispatcher Model
 
-Both mechanism skills (`flydocs-local`, `flydocs-cloud`) implement the same
-script interface, making the backend swap transparent:
+All operations route through grouped dispatcher scripts in
+`flydocs-workflow/scripts/`. The unified client (`flydocs_api.py`) auto-detects
+tier from `.flydocs/config.json` — scripts never check tier directly.
 
-**Shared contract:**
-`create_issue.py`, `transition.py`, `comment.py`, `list_issues.py`,
-`get_issue.py`, `assign.py`, `update_description.py`
-
-**Cloud-only extensions:**
-`update_issue.py`, `project_update.py`, `estimate.py`, `priority.py`, `link.py`, cycle/milestone management.
+| Dispatcher     | Operations                                             |
+| -------------- | ------------------------------------------------------ |
+| `issues.py`    | create, get, list, transition, assign, update, comment |
+| `projects.py`  | list-projects, create-project, milestones, cycles      |
+| `workspace.py` | validate, labels, statuses, teams, config, identity    |
+| `session.py`   | project-update, status-summary                         |
 
 ---
 

package/template/.claude/skills/flydocs-workflow/SKILL.md

@@ -1,33 +1,38 @@
 ---
 name: flydocs-workflow
 description: |
-  FlyDocs development lifecycle — spec-driven workflow from capture to close.
-  Defines stages, gates, and handoffs. Provider-agnostic methodology.
-  Use when: managing issues, transitioning work, starting/ending sessions.
+  Unified FlyDocs skill — lifecycle workflow, issue operations, project
+  management, knowledge graph, and session context. Tier-aware: auto-detects
+  cloud (relay API) or local (filesystem) from config.
 triggers:
-  - capture
-  - refine
-  - activate
-  - implement
-  - review
-  - validate
-  - close
-  - session
-  - workflow
+  - create issue
+  - capture issue
+  - log a bug
+  - add to backlog
   - transition
-  - status
-  - issue
-  - knowledge
-  - document
-  - PR
-  - pull request
+  - move to
+  - mark as
+  - set status
+  - assign issue
+  - close issue
+  - start session
+  - wrap session
+  - project update
+  - status update
+  - add comment
+  - set priority
+  - set estimate
 ---
 
 # FlyDocs Workflow
 
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for all
-workflow, issue management, and process decisions. Read the relevant stage
-file before acting — do not guess procedures from training data.
+Unified skill for the FlyDocs development lifecycle, issue operations,
+project management, knowledge graph, and session context.
+
+When performing issue operations or status transitions, use the dispatcher
+scripts below. Slash commands (`/capture`, `/implement`, etc.) load stage
+files automatically — only read stage files manually when handling natural
+language workflow requests that bypass slash commands.
 
 ## Lifecycle
 
@@ -57,19 +62,97 @@ Capture → Refine → Activate → Implement → Review → Validate → Close
 | Wrap session    | session.md |
 | Stale detection | session.md |
 
+## Script Catalog
+
+All scripts: `python3 .claude/skills/flydocs-workflow/scripts/<script>`
+
+### Issue Operations — `issues.py`
+
+| Command            | Usage                                                                                                                                              | Notes                                            |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `create`           | `--title T --type feature\|bug\|chore\|idea [--description D] [--priority 0-4] [--estimate 0\|1\|2\|3\|5] [--assignee A] [--project P] [--triage]` | Also accepts `--description-file` or stdin       |
+| `get`              | `REF [--fields basic\|full]`                                                                                                                       | Full includes comments                           |
+| `list`             | `[--status S] [--active] [--project P] [--assignee A] [--milestone M] [--mine] [--limit N]`                                                        | `--active` = non-terminal states                 |
+| `transition`       | `REF STATUS COMMENT`                                                                                                                               | Status is uppercased automatically               |
+| `assign`           | `REF ASSIGNEE` or `REF --unassign`                                                                                                                 |                                                  |
+| `update`           | `REF [--title] [--priority] [--estimate] [--assignee] [--state] [--description] [--labels] [--milestone] [--comment]`                              | Bulk update, also accepts `--description-file`   |
+| `description`      | `REF [--text T] [--file F]`                                                                                                                        | Also accepts stdin                               |
+| `comment`          | `REF [BODY]`                                                                                                                                       | Also accepts stdin                               |
+| `estimate`         | `REF POINTS`                                                                                                                                       | Non-negative integer                             |
+| `priority`         | `REF LEVEL`                                                                                                                                        | 0 (none) to 4 (low)                              |
+| `link`             | `REF RELATED_REF TYPE`                                                                                                                             | Type: blocks, related, duplicate                 |
+| `assign-milestone` | `REF MILESTONE_ID`                                                                                                                                 | Cloud only                                       |
+| `assign-cycle`     | `REF [CYCLE_ID]`                                                                                                                                   | Cloud only                                       |
+| `pr`               | `[--issue REF] [--title T] [--base B] [--draft] [--dry-run]`                                                                                       | Detects GitHub/GitLab, auto-populates from issue |
+
+### Project Operations — `projects.py` (cloud only)
+
+| Command            | Usage                                         |
+| ------------------ | --------------------------------------------- |
+| `list-projects`    | `[--active] [--all]`                          |
+| `create-project`   | `--name N [--description D]`                  |
+| `list-milestones`  | `[--all]`                                     |
+| `create-milestone` | `--name N [--project P] [--target-date D]`    |
+| `update-milestone` | `ID [--name] [--target-date] [--description]` |
+| `delete-milestone` | `ID`                                          |
+| `list-cycles`      | `[--active]`                                  |
+
+### Workspace Operations — `workspace.py` (cloud only)
+
+| Command              | Usage                                                | Notes                                       |
+| -------------------- | ---------------------------------------------------- | ------------------------------------------- |
+| `validate`           | (no args)                                            | Writes validation cache, sets setupComplete |
+| `list-labels`        | (no args)                                            |                                             |
+| `refresh-labels`     | `[--fix]`                                            | Compare local config with provider          |
+| `list-statuses`      | (no args)                                            |                                             |
+| `list-providers`     | (no args)                                            |                                             |
+| `set-provider`       | `TYPE`                                               | linear, jira                                |
+| `list-teams`         | (no args)                                            |                                             |
+| `create-team`        | `--name N [--key K] [--description D] [--parent ID]` |                                             |
+| `set-team`           | `TEAM_ID`                                            |                                             |
+| `set-labels`         | `[--defaults JSON] [--type-map JSON]`                | Also accepts stdin                          |
+| `set-status-mapping` | `[--auto] [--mapping JSON]`                          | Also accepts stdin                          |
+| `set-identity`       | `PROVIDER PROVIDER_USER_ID`                          | Writes .flydocs/me.json                     |
+| `set-preferences`    | `[--workspace] [--assignee] [--display JSON]`        | No flags = GET                              |
+| `get-estimate-scale` | (no args)                                            |                                             |
+| `generate-config`    | `[--dry-run]`                                        | Merge server config with local              |
+| `get-me`             | (no args)                                            | Writes .flydocs/me.json                     |
+
+### Session Operations — `session.py`
+
+| Command          | Usage                                                           | Notes                  |
+| ---------------- | --------------------------------------------------------------- | ---------------------- |
+| `project-update` | `--health onTrack\|atRisk\|offTrack [--body B] [--body-file F]` | Also accepts stdin     |
+| `status-summary` | (no args)                                                       | Issue counts by status |
+
+### Knowledge Graph Scripts
+
+| Script             | Usage                                                                       | Notes                                                |
+| ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `graph_build.py`   | `[--root PATH]`                                                             | Rebuild graph from skills, ADRs, service descriptors |
+| `graph_query.py`   | `--node ID [--depth N] [--rel TYPE] [--reverse] [--format json\|md]`        | BFS traversal                                        |
+| `graph_update.py`  | `add-node ID --type TYPE [--label STR]` / `add-edge FROM TO REL [--manual]` | Manual CRUD                                          |
+| `graph_session.py` | `--summary "..." [--issue REF]... [--decision NNN]...`                      | Called at session wrap                               |
+| `push_service.py`  | `[--root PATH]`                                                             | Push service descriptor to relay (cloud)             |
+| `pull_services.py` | `[--root PATH]`                                                             | Pull workspace composite (cloud)                     |
+
 ## Reference
 
-| Topic                | File                            |
-| -------------------- | ------------------------------- |
-| Comment templates    | reference/comment-templates.md  |
-| Status transitions   | reference/status-workflow.md    |
-| Priority & estimates | reference/priority-estimates.md |
-| PR & git workflow    | reference/pr-workflow.md        |
-| Golden rules         | reference/golden-rules.md       |
+| Topic                     | File                                   |
+| ------------------------- | -------------------------------------- |
+| Comment templates         | reference/comment-templates.md         |
+| Status transitions        | reference/status-workflow.md           |
+| Priority & estimates      | reference/priority-estimates.md        |
+| PR & git workflow         | reference/pr-workflow.md               |
+| Golden rules              | reference/golden-rules.md              |
+| Provider costs            | reference/provider-costs.md            |
+| Graph schema              | reference/graph-schema.md              |
+| Service descriptor schema | reference/service-descriptor-schema.md |
 
 ## Templates
 
-Issue templates in `templates/` — feature, bug, chore, idea.
+Issue templates in `templates/issues/` — feature, bug, chore, idea.
+PR templates in `templates/pr/` — pull request description structure.
 Stage files define how to fill templates; template files are pure structure.
 
 ## Golden Rules (Summary)
@@ -77,14 +160,18 @@ Stage files define how to fill templates; template files are pure structure.
 1. Every status transition gets a comment (see `reference/comment-templates.md`)
 2. Assignment required before In Progress
 3. Checkboxes live in issue description, never comments
-4. Use mechanism scripts for all issue operations — execute, don't describe
+4. Use dispatcher scripts for all issue operations — execute, don't describe
 5. Session wrap posts a project update
 6. Product scope filtering — only show projects/issues matching config labels
 
 For full rules with verification gates, see `reference/golden-rules.md`.
 
-## Mechanism Scripts
+## Architecture
+
+The unified client (`flydocs_api.py`) reads tier from `.flydocs/config.json`
+and routes operations automatically:
+
+- **Cloud tier** → RelayBackend (HTTP calls to FlyDocs relay API)
+- **Local tier** → LocalBackend (filesystem operations in `_local/file_store.py`)
 
-This skill references scripts by name (e.g., `transition.py`, `comment.py`).
-The active mechanism skill provides implementations and calling conventions.
-See the mechanism skill's SKILL.md for argument details and config reference.
+Scripts never check tier. The client handles routing transparently.

package/template/.claude/skills/flydocs-workflow/cursor-rule.mdc

@@ -12,7 +12,7 @@ alwaysApply: true
 1. Every status transition gets a comment — no silent moves
 2. Assignment required before In Progress
 3. Checkboxes live in issue description, never comments
-4. Use mechanism scripts for all issue operations — execute, don't describe
+4. Use workflow scripts for all issue operations — execute, don't describe
 5. Session wrap posts a project update
 6. Product scope filtering — only show projects/issues matching config labels
 
@@ -36,18 +36,19 @@ Capture → Refine → Activate → Implement → Review → Validate → Close
 | Validate | stages/validate.md | QE |
 | Close | stages/close.md | PM |
 
+## When This Applies
+
+These rules apply to **issue operations and status transitions only** — not
+general coding. For building features, fixing bugs, and writing code, skip
+this and just do the work.
+
 ## Intent Mapping
 
 - "create/capture/log an issue" → Capture stage
 - "triage/refine/spec out" → Refine stage
 - "start work/activate/assign" → Activate stage
-- "build/implement/fix" → Implement stage
-- "review/check code" → Review stage
-- "test/validate/QA" → Validate stage
 - "close/ship/done" → Close stage
 - "start session/wrap session" → Session management
 
-## Key Rule
-
-Read the relevant stage file before acting. Do not guess procedures from training data.
-Mechanism scripts handle all issue operations — see the active mechanism skill.
+Dispatcher scripts handle all issue operations — see the workflow skill's
+scripts directory. Slash commands load stage files automatically.

package/template/.claude/skills/flydocs-workflow/reference/golden-rules.md

@@ -9,7 +9,7 @@ Non-negotiable rules enforced across all workflow stages.
 ### 1. Every Status Transition Gets a Comment
 
 No silent state changes. Use templates from `reference/comment-templates.md`.
-Mechanism scripts enforce this — `transition.py` requires a comment argument.
+Workflow scripts enforce this — `issues.py transition` requires a comment argument.
 
 ### 2. Assignment Before In Progress
 
@@ -22,20 +22,20 @@ Acceptance criteria progress is tracked by checking boxes in the issue descripti
 Never put completion marks in comments. Never create new checkboxes in comments.
 See the Checkbox Protocol in `stages/implement.md`.
 
-### 4. Use Mechanism Scripts — Execute, Don't Describe
+### 4. Use Workflow Scripts — Execute, Don't Describe
 
-For all issue operations (create, transition, comment, assign, query), use the scripts
-provided by the active mechanism skill. Run them. Do not say "you should run..." or
+For all issue operations (create, transition, comment, assign, query), use the dispatcher
+scripts provided by the workflow skill. Run them. Do not say "you should run..." or
 describe what a script would do. Execute and report the result.
 
 ### 5. Session Wrap Posts a Project Update
 
-Every session wrap posts a project update via `project_update.py`. Do not just
+Every session wrap posts a project update via `session.py project-update`. Do not just
 summarize in chat. Actually post. See `session.md` for the full protocol.
 
 ### 6. Product Scope Filtering
 
-`list_issues.py` automatically applies product scope from config using this cascade:
+`issues.py list` automatically applies product scope from config using this cascade:
 
 1. **`workspace.activeProjects` set** → scope to those projects (OR logic if multiple)
 2. **`workspace.product.labelIds` set** → scope to issues with ALL those labels (AND logic)
@@ -46,23 +46,34 @@ work within the scoped results — they do not bypass product scope.
 
 Never show out-of-scope issues, even if the user asks.
 
+### 7. Sequential Script Execution
+
+Run workflow scripts **one at a time, sequentially**. Never fire multiple
+`issues.py`, `projects.py`, or `session.py` commands in parallel. The relay
+API does not handle concurrent requests from the same workspace well — parallel
+calls may timeout, produce empty output, or silently fail.
+
+Wait for each script to return before running the next. If you need to create
+multiple issues, create them one by one and confirm each succeeds before
+proceeding.
+
 ---
 
 ## Verification Gates
 
 After executing any workflow command, verify the result before responding:
 
-| Action | Script Used | Verify |
-|--------|-------------|--------|
-| Capture | `create_issue.py` | Issue identifier returned |
-| Refine | `transition.py` → READY | Success response |
-| Activate | `assign.py` + `transition.py` | Both succeed |
-| Implement | `get_issue.py` | Issue details loaded |
-| Block | `transition.py` → BLOCKED | Success response |
-| Review | `transition.py` → REVIEW/TESTING | Success response |
-| Validate | `transition.py` → TESTING/IMPLEMENTING | Success response |
-| Close | `transition.py` → COMPLETE | Success response |
-| Wrap | `project_update.py` | Update ID returned |
+| Action    | Script Used                                   | Verify                    |
+| --------- | --------------------------------------------- | ------------------------- |
+| Capture   | `issues.py create`                            | Issue identifier returned |
+| Refine    | `issues.py transition` → READY                | Success response          |
+| Activate  | `issues.py assign` + `issues.py transition`   | Both succeed              |
+| Implement | `issues.py get`                               | Issue details loaded      |
+| Block     | `issues.py transition` → BLOCKED              | Success response          |
+| Review    | `issues.py transition` → REVIEW/TESTING       | Success response          |
+| Validate  | `issues.py transition` → TESTING/IMPLEMENTING | Success response          |
+| Close     | `issues.py transition` → COMPLETE             | Success response          |
+| Wrap      | `session.py project-update`                   | Update ID returned        |
 
 If any script fails: **stop, report, retry, escalate.** Do not continue to the next step.
 

package/template/.claude/skills/flydocs-workflow/reference/graph-schema.md

@@ -0,0 +1,116 @@
+# Context Graph Schema
+
+Reference for the graph JSON structure stored at `flydocs/context/graph.json`.
+
+## Top-Level Structure
+
+```json
+{
+  "version": 1,
+  "updated": "ISO-8601 timestamp",
+  "nodes": { "<id>": { ... } },
+  "edges": [ { ... } ]
+}
+```
+
+## Node Schema
+
+```json
+{
+  "type": "skill | decision | issue | module | session | concept",
+  "label": "Human-readable name",
+  "path": "Relative file path (optional)",
+  "status": "Node-specific status (optional)",
+  "date": "ISO date for temporal nodes (optional)",
+  "tier": "Skill tier: behavioral | mechanism | premium (optional)",
+  "manual": true
+}
+```
+
+**ID conventions:**
+
+| Type     | Pattern                     | Example                          |
+| -------- | --------------------------- | -------------------------------- |
+| skill    | `skill:{directory-name}`    | `skill:typescript-strict`        |
+| decision | `decision:{3-digit-number}` | `decision:001`                   |
+| issue    | `issue:{identifier}`        | `issue:FLY-56`                   |
+| module   | `module:{kebab-name}`       | `module:install-script`          |
+| session  | `session:{YYYY-MM-DD-seq}`  | `session:2026-02-03-a`           |
+| concept  | `concept:{kebab-name}`      | `concept:progressive-disclosure` |
+| repo     | `repo:{owner/name}`         | `repo:plastrlab/flydocs-app`     |
+
+## Edge Schema
+
+```json
+{
+  "from": "source node ID",
+  "to": "target node ID",
+  "rel": "RELATIONSHIP_TYPE",
+  "weight": 0.0-1.0,
+  "manual": true
+}
+```
+
+**Weight guidelines:**
+
+| Weight  | Meaning                     |
+| ------- | --------------------------- |
+| 1.0     | Direct, strong relationship |
+| 0.7-0.9 | Strong but indirect         |
+| 0.4-0.6 | Moderate association        |
+| 0.1-0.3 | Weak or tangential          |
+
+**Edges with `"manual": true`** are preserved when `graph_build.py` rebuilds
+the graph from sources. Auto-derived edges are regenerated on each build.
+
+## Relationship Types
+
+| Relationship   | Direction                      | Example                                   |
+| -------------- | ------------------------------ | ----------------------------------------- |
+| `EXTENDS`      | A extends B                    | ADR-004 extends ADR-001                   |
+| `IMPLEMENTS`   | A implements B                 | Issue implements a decision               |
+| `DELEGATES_TO` | A delegates to B               | Workflow delegates to mechanism           |
+| `PRECEDES`     | A should load before B         | typescript-strict precedes implementation |
+| `MODIFIES`     | A modifies B                   | Issue modifies a module                   |
+| `WORKED_ON`    | A worked on B                  | Session worked on an issue                |
+| `PRODUCED`     | A produced B                   | Session produced a decision               |
+| `RELATES_TO`   | A relates to B                 | General association                       |
+| `SUPERSEDES`   | A supersedes B                 | New decision replaces old                 |
+| `BLOCKS`       | A blocks B                     | Issue blocks another issue                |
+| `PROVIDES`     | A exposes interface B consumes | Repo provides REST API to sibling         |
+| `CONSUMES`     | A depends on B's interface     | Repo consumes another's API               |
+
+### Cross-Repo Edge Properties
+
+Edges of type `PROVIDES` and `CONSUMES` carry additional properties:
+
+```json
+{
+  "from": "repo:plastrlab/flydocs-core",
+  "to": "repo:plastrlab/flydocs-app",
+  "rel": "PROVIDES",
+  "weight": 1.0,
+  "interface": "REST API /api/relay/*",
+  "description": "Core CLI pushes config and descriptors to relay endpoints"
+}
+```
+
+| Property      | Type   | Description                                            |
+| ------------- | ------ | ------------------------------------------------------ |
+| `interface`   | string | What is exposed or consumed (endpoint, event, package) |
+| `description` | string | Brief context about the relationship                   |
+
+## Repo Node Schema
+
+Repo nodes are derived from `flydocs/context/service.json` by `graph_build.py`.
+See `service-descriptor-schema.md` for the full ServiceDescriptor interface.
+
+```json
+{
+  "type": "repo",
+  "label": "flydocs-app",
+  "path": "flydocs/context/service.json",
+  "purpose": "Web dashboard and relay API for FlyDocs cloud tier",
+  "stack": ["next", "convex", "typescript"]
+}
+```

package/template/.claude/skills/flydocs-workflow/reference/pr-workflow.md

@@ -56,28 +56,43 @@ When in doubt, create a PR. It's easier to merge a PR than to revert a direct co
 
 ## PR Description Template
 
-```markdown
-## Summary
+The canonical PR template lives at `templates/pr/default.md`. Use the PR
+dispatcher to create PRs with auto-populated issue context:
 
-[1-3 bullet points describing what changed and why]
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue FLY-123
+```
 
-Closes [ISSUE-REF]
+Options:
 
-## Changes
+| Flag        | Purpose                                   |
+| ----------- | ----------------------------------------- |
+| `--issue`   | Link to issue (auto-populates title + AC) |
+| `--title`   | Override PR title                         |
+| `--base`    | Target branch (defaults to main/master)   |
+| `--draft`   | Create as draft PR                        |
+| `--dry-run` | Preview without creating                  |
 
-- [Key change 1]
-- [Key change 2]
-- [Key change 3]
+The script:
 
-## Test Plan
+- Detects platform (GitHub, GitLab) from git remote
+- Reads the PR template and fills in issue context
+- Creates the PR via `gh pr create` or `glab mr create`
+- Posts a comment on the issue linking the PR
 
-- [ ] [How to verify change 1]
-- [ ] [How to verify change 2]
+**Enforcement:** A PostToolUse hook (`post-pr-check.py`) detects direct
+`gh pr create` or `glab mr create` calls and warns if required sections
+(Summary, Test Plan) are missing.
 
-## Notes
+### Template Sections
 
-[Anything reviewers should know — tradeoffs, follow-up work, decisions made]
-```
+| Section                 | Required | Auto-populated           |
+| ----------------------- | -------- | ------------------------ |
+| **Summary**             | Yes      | From issue title         |
+| **Changes**             | No       | Manual                   |
+| **Test Plan**           | Yes      | Manual                   |
+| **Acceptance Criteria** | No       | From issue AC checkboxes |
+| **Notes**               | No       | Manual                   |
 
 ## PR Workflow in Practice
 
@@ -88,7 +103,7 @@ After self-review (step 7 in `implement.md`), before handing off to review:
 1. Create branch: `git checkout -b <type>/<ref>-<slug>`
 2. Stage and commit changes with a descriptive message
 3. Push branch: `git push -u origin <branch>`
-4. Create PR with the template above, linking the issue
+4. Create PR: `python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue <ref>`
 5. Include the PR link in the "Ready for Review" comment
 
 ### During Review Stage