@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/plans/workflow-categories-discovery.md

@@ -0,0 +1,110 @@
+# Workflow Categories & Category-First Discovery
+
+## Context / Ask
+
+The workflow catalog has grown to ~36 items (25 JSON files + routines + bundled). A flat `list_workflows` call returns all of them with full descriptions, consuming 3-5K tokens. Agents often don't know the exact workflow ID — they know the task family. Design category-first discovery: categories as metadata, `list_workflows` returns a summary when called without a category filter.
+
+## Path Recommendation
+
+`landscape_first` — the problem and desired outcome are clear. The key unknowns are implementation shape (where categories live, how the contract changes) and what the natural category taxonomy looks like for the current catalog. Understanding these grounds the design decision.
+
+## Constraints / Anti-goals
+
+- Must not break existing `list_workflows` callers (additive, not breaking)
+- Categories must not require maintaining a parallel structure that drifts
+- `list_workflows` contract change must be backwards-compatible
+
+## Landscape Packet
+
+*(to be populated)*
+
+## Problem Frame Packet
+
+*(to be populated)*
+
+## Candidate Directions
+
+*(to be populated)*
+
+## Challenge Notes
+
+*(to be populated)*
+
+## Resolution Notes
+
+*(to be populated)*
+
+## Decision Log
+
+*(to be populated)*
+
+## Final Summary
+
+*(to be populated)*
+
+## Final Summary
+
+### Selected Direction: Candidate A — spec overlay + category filter
+
+**Confidence: High.** Three candidates evaluated, challenged, reviewed. No direction changes required.
+
+### Implementation shape
+
+**1. `spec/workflow-categories.json`** (new file)
+```json
+{
+  "categories": [
+    { "id": "coding", "displayName": "Coding & Development" },
+    { "id": "review_audit", "displayName": "Review & Audit" },
+    { "id": "investigation", "displayName": "Investigation & Debugging" },
+    { "id": "design", "displayName": "Design & Discovery" },
+    { "id": "documentation", "displayName": "Documentation" },
+    { "id": "tickets", "displayName": "Tickets & Planning" },
+    { "id": "learning", "displayName": "Learning & Personal" },
+    { "id": "routines", "displayName": "Routines (Internal)" },
+    { "id": "authoring", "displayName": "Workflow Authoring" },
+    { "id": "testing", "displayName": "Testing & Diagnostics" }
+  ],
+  "workflows": {
+    "mr-review-workflow-agentic": { "category": "review_audit" },
+    "bug-investigation-agentic": { "category": "investigation" },
+    "coding-task-workflow-agentic": { "category": "coding" },
+    "test-session-persistence": { "category": "testing", "hidden": true },
+    ...
+  }
+}
+```
+
+**2. `V2ListWorkflowsInput`**: add `category?: string`
+
+**3. `V2WorkflowListOutputSchema`**: add `categorySummary?: { id, displayName, count, representatives }[]`
+
+**4. Response contract:**
+- No `category` passed → `{ workflows: [], categorySummary: [...10 categories with counts...] }` (~500 tokens)
+- `category=coding` → `{ workflows: [...full list for coding...], categorySummary: undefined }` (~800 tokens)
+
+**5. `validate:registry`**: error (not warning) on uncategorized non-hidden workflows
+
+**6. `list_workflows` tool description**: update to explain category browsing
+
+### Decision Log
+
+- A (spec overlay) selected: hash stable, backwards compatible, CI-checkable, follows includeSources pattern
+- B (convention inference) rejected: only covers ~30% of catalog reliably  
+- C (embedded with hash isolation) rejected: compiler complexity for no gain over A
+- Challenge: two-call adoption risk — resolved, summary is DEFAULT not opt-in
+- Orange finding: response contract clarified (`workflows: []` + `categorySummary` when no category passed)
+
+### Residual risks
+
+1. Per-workspace custom categories deferred to v2
+2. Routines visibility (show in summary or hide?) — open question, recommend show with "Routines (Internal)" label
+3. validate:registry must not be removable without replacing the uncategorized-workflow check
+
+### 5 open questions to resolve before building
+
+1. Should `testing` workflows be `hidden: true` or shown in summary?
+2. Should routines appear in summary or be hidden?  
+3. Should `categorySummary` include a short description per category?
+4. What display name for `review_audit`?
+5. Should workflow-for-workflows Phase 7 prompt for category?

package/docs/plans/workflow-categories-review.md

@@ -0,0 +1,51 @@
+# Workflow Categories Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Condition of failure |
+|---|---|---|
+| Two-file maintenance | Acceptable | If validate:registry check removed — uncategorized workflows silently absent |
+| Two-call pattern | Acceptable | Summary is DEFAULT — no agent behavior change needed for token savings |
+| Overlay drift | Acceptable | With CI enforcement (validate:registry must treat uncategorized non-hidden as error) |
+
+## Failure Mode Review
+
+| Failure Mode | Risk | Coverage | Fix |
+|---|---|---|---|
+| New workflow not categorized | Medium | validate:registry warning | Upgrade to error for non-hidden workflows |
+| Agent passes unknown category | Low | Returns empty list | Add hint listing valid categories in response |
+| **Existing callers break** | **High** | **Not yet addressed** | **`categorySummary` must be ADDITIVE — keep `workflows` in response** |
+
+**Most dangerous**: existing callers that iterate `workflows` will get an empty array if we change the default to summary-only. Fix: when no `category` is passed, return `categorySummary` (new field) PLUS `workflows: []` (existing field, now empty). Callers that check `workflows` see empty and know to browse by category.
+
+## Runner-Up / Simpler Alternative Review
+
+No runner-up worth borrowing from. Simpler variant (no validate:registry check) rejected — silent data loss is worse than maintenance burden.
+
+## Philosophy Alignment
+
+All principles satisfied: determinism (explicit overlay), validate-at-boundaries (CI check), YAGNI (no compiler changes), explicit domain types (typed enum).
+
+Minor acceptable tension: empty `workflows` array in summary response is technically correct but slightly awkward UX.
+
+## Findings
+
+**Orange — backward compatibility not fully specified**
+The current design description doesn't explicitly address what `workflows` contains when no `category` is passed. If it returns all workflows (current behavior), the token savings are lost. If it returns empty, existing callers break. Must explicitly specify: `workflows: []` when in summary mode, `categorySummary` is the new primary field.
+
+**Yellow — validate:registry check must be error, not warning**
+An uncategorized non-hidden workflow that shows as a warning doesn't block CI. Should be an error so new workflows can't ship without a category.
+
+**Yellow — tool description in tools.ts needs updating**
+The `list_workflows` tool description says it returns workflow details. It needs to explain the new summary default and the `category` parameter.
+
+## Recommended Revisions
+
+1. Specify response contract explicitly: when `category` absent → `{ workflows: [], categorySummary: [...] }`; when `category` present → `{ workflows: [...full list...], categorySummary: undefined }`
+2. validate:registry: treat uncategorized non-hidden workflows as an **error** (not warning) in CI
+3. Update `list_workflows` tool description to explain category browsing
+
+## Residual Concerns
+
+- Per-workspace custom categories not addressed (v2 concern, not v1)
+- Should routines be hidden from summary by default? They're internal plumbing, not user-invoked. Recommend: routines visible in summary but clearly labeled, agents can filter by category=routines when needed

package/docs/plans/workflow-discovery-model-candidates.md

@@ -0,0 +1,94 @@
+# Workflow Discovery Model: Design Candidates
+
+## Problem Understanding
+
+**The real seam**: The `description` field already exists on every workflow. The problem is descriptions are written as marketing copy, not as intent phrases. The category layer is a symptom of descriptions not carrying enough signal for agents to match on.
+
+**Core tensions:**
+1. Human browsing vs. agent matching — humans scan groups visually; agents match text probabilistically
+2. Compact summary vs. enough signal — 500 tokens only helps if the signal density is right
+3. Multi-fit workflows — forcing single assignment loses information
+4. Taxonomy maintenance vs. description maintenance — both together is double burden
+
+**Key insight**: categories organize by type ("what kind of thing is this?"), agents need organization by intent ("when would I use this?"). These are different questions.
+
+## Philosophy Constraints
+
+- **Determinism**: `when` phrases must be explicitly authored, not computed or inferred
+- **YAGNI**: don't add tags/embeddings before evidence they're needed
+- **Explicit domain types**: intent phrases must be first-class authored fields, not derived
+
+## Candidates
+
+### A: Better descriptions only (too narrow)
+
+Rewrite all 36 workflow descriptions as intent phrases. No categories, no overlay.
+
+- **Fixes**: agent matching quality on second call
+- **Doesn't fix**: 500-token first call (36 descriptions = ~3K tokens)
+- **Scope**: too narrow — prerequisite, not a solution
+
+### B: Categories + `when` phrases in categorySummary ✓ RECOMMENDED
+
+Keep categories as the organizing layer. Enrich `categorySummary` with a `when: [...]` array of 2-4 intent phrases per category.
+
+**Example first call (~500 tokens):**
+```json
+{
+  "categorySummary": [
+    {
+      "id": "review_audit",
+      "displayName": "Review & Audit",
+      "count": 3,
+      "when": ["reviewing a merge request", "auditing production readiness", "checking architecture scalability"]
+    },
+    {
+      "id": "investigation",
+      "displayName": "Investigation & Debugging",
+      "count": 2,
+      "when": ["diagnosing a bug in code", "diagnosing tool or environment issues"]
+    }
+  ]
+}
+```
+
+- **Fixes**: 500-token budget, human browsing (categories), agent intent matching (`when` phrases), multi-fit (multiple `when` phrases can reference overlapping use cases across categories)
+- **Maintenance**: per-category (9 entries), not per-workflow (36 entries)
+- **Failure mode**: `when` phrases too coarse — agent can't distinguish within a category. Solvable by writing better phrases.
+- **Scope**: best-fit
+- **Philosophy**: honors determinism (authored explicitly), YAGNI (minimal addition)
+
+### C: Intent clusters without categories (too broad)
+
+Per-workflow `triggers` array, clustered dynamically into groups with computed labels.
+
+- **Fixes**: multi-fit perfectly
+- **Breaks**: determinism (computed clusters shift), 36x maintenance burden, YAGNI
+- **Scope**: too broad — solves a problem we don't yet have
+
+### D: Tags + categories (too broad)
+
+Primary category for human browsing, multiple tags for multi-fit intent signals.
+
+- **Fixes**: multi-fit
+- **Breaks**: YAGNI (tags before evidence needed), governance burden
+- **Scope**: too broad
+
+## Comparison and Recommendation
+
+**B + A together.** B handles compactness and both human/agent discovery. A (better descriptions) is B's prerequisite — it improves the second call after agents pick a category.
+
+The `when` array lives at the **category level** (9 entries), not the workflow level (36 entries). This is the key: low maintenance cost, high signal density, no taxonomy proliferation.
+
+## Self-Critique
+
+**Strongest counter-argument**: `when` phrases at category level are too coarse. An agent wanting a "security review" won't find it if `when` only says "reviewing a merge request." Counter: this is a description quality problem in the phrases, not structural — write better phrases.
+
+**Pivot condition**: if agents still mis-select after good `when` phrases, move to per-workflow `triggers` authored as explicit fields (not computed). Candidate C's structure, A's maintenance discipline.
+
+## Open Questions
+
+1. Who maintains the `when` phrases — inline in `spec/workflow-categories.json` alongside the category definitions?
+2. How many `when` phrases per category? 3-5 seems right but worth confirming.
+3. Should `when` phrases be surfaced in the `workrail://categories` MCP resource so agents can read them before calling `list_workflows`?
+4. Does A (better descriptions) ship in the same PR or separately?

package/docs/plans/workflow-discovery-model-discovery.md

@@ -0,0 +1,74 @@
+# Workflow Discovery Model: Alternatives to Categories
+
+## Context / Ask
+
+Hierarchical categories break down when items fit multiple buckets or none. Exploring whether a superior organization model exists for WorkRail's ~36 workflow catalog, specifically for token-efficient agent discovery.
+
+## Path Recommendation
+
+`full_spectrum` — problem framing matters here. The wrong model will feel natural to build but create friction in practice. Need both landscape (what models exist) and reframing (what do agents actually need when discovering workflows).
+
+## Constraints / Anti-goals
+
+- Must keep first `list_workflows` call compact (~500 tokens)
+- Must be maintainable — no model that requires constant curation to stay accurate
+- Must work for agents (text-based, probabilistic matching) not just humans (visual scanning)
+
+## Landscape Packet
+
+*(to be populated)*
+
+## Problem Frame Packet
+
+*(to be populated)*
+
+## Candidate Directions
+
+*(to be populated)*
+
+## Challenge Notes / Resolution Notes / Decision Log / Final Summary
+
+*(to be populated)*
+
+## Final Summary
+
+### Selected Direction: B + A — Categories with `when` phrases + intent-oriented descriptions
+
+**Confidence: High.**
+
+### The enriched `categorySummary` response
+
+Each category entry in the first `list_workflows` call contains:
+- `id`: stable identifier
+- `displayName`: human-readable name  
+- `count`: number of workflows
+- `when: string[]`: 3-5 intent phrases agents match against ("reviewing a merge request before merging", "auditing a service before deployment")
+- `examples: string[]`: 1-2 representative workflow IDs for agents that recognize names
+
+**First call (~500 tokens)** → agent reads `when` phrases, picks category  
+**Second call with `category=`** → agent reads intent-oriented `description` per workflow, picks specific workflow
+
+### Workflow descriptions (A component)
+
+All 36 workflow descriptions rewritten as intent phrases: "Use this to [verb] [object] [context]". Ships in same PR as the category changes.
+
+### What changed from original Candidate A (prior session)
+
+The original spec overlay + category filter design is unchanged structurally. The key additions:
+1. Each category gains a `when: string[]` array in `spec/workflow-categories.json`
+2. Each category gains an `examples: string[]` array (1-2 workflow IDs)
+3. All workflow `description` fields rewritten as intent phrases
+4. `workrail://categories` MCP resource exposes `when` phrases so agents can read them independently
+5. Authoring guidelines added as comments in `spec/workflow-categories.json`
+
+### Decision Log
+
+- A alone (better descriptions) rejected: doesn't solve 500-token first call
+- C (per-workflow triggers) rejected for now: unnecessary maintenance burden; it's the pivot condition if B proves insufficient
+- D (tags) rejected: YAGNI
+- B selected: categories + `when` phrases at category level. Low maintenance (9 entries), high signal density, both human and agent discovery served
+
+### Residual risks
+
+1. `when` phrase quality is load-bearing — content quality problem, not structural. Authoring guidelines mitigate.
+2. Per-workflow triggers (C evolved) remains the right escalation if `when` phrases prove too coarse after real usage.

package/docs/plans/workflow-discovery-model-review.md

@@ -0,0 +1,48 @@
+# Workflow Discovery Model: Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Condition of failure |
+|---|---|---|
+| Single-category assignment per workflow | Acceptable | If a workflow genuinely spans two unrelated domains (none currently do) |
+| `when` phrases at category level | Acceptable | If phrases written lazily rather than specifically |
+| Two-call pattern | Acceptable | Agents already willing to make second calls; first call is cheap |
+
+## Failure Mode Review
+
+| Mode | Risk | Coverage |
+|---|---|---|
+| `when` phrases too coarse | Medium — content quality risk | Write phrases with concrete examples, not abstractions |
+| Descriptions not updated | Medium | A+B ship together in same PR |
+| Multi-fit miscategorization | Low | `when` phrases can overlap across categories |
+
+**Highest risk**: lazy `when` phrases. Quality of this content determines whether the first call actually helps agents.
+
+## Runner-Up / Simpler Alternative Review
+
+- Runner-up (C evolved) has nothing to borrow now; it's the pivot condition if B proves insufficient
+- Simpler variant (A only) doesn't solve 500-token first call
+- **Hybrid opportunity**: add small `examples` array per category (1-2 specific workflow IDs) alongside `when`. Lets experienced agents short-circuit the second call. Low cost, high value.
+
+## Philosophy Alignment
+
+All principles satisfied: determinism (explicitly authored), YAGNI, explicit domain types, validate-at-boundaries.
+
+## Findings
+
+**Yellow — `when` phrase quality is load-bearing**
+The entire value of B depends on `when` phrases being written specifically enough for agents to match ('before merging a PR', not 'reviewing code'). No structural enforcement exists. Add authoring guidelines as comments in `spec/workflow-categories.json`.
+
+**Yellow — `examples` field is a low-cost improvement**
+Adding 1-2 representative workflow IDs per category in the summary response lets agents short-circuit the second call if they recognize a workflow name. Should be included in the design.
+
+## Recommended Revisions
+
+1. Add `examples: string[]` (1-2 workflow IDs) to each category entry in `spec/workflow-categories.json` and the `categorySummary` response
+2. Add authoring guidelines as comments in `spec/workflow-categories.json` explaining how to write good `when` phrases
+3. Descriptions (A component) must ship in same PR as B
+
+## Residual Concerns
+
+- Per-workflow triggers (C evolved) remains the right pivot if `when` phrases prove too coarse after real usage
+- `workrail://categories` MCP resource should expose `when` phrases so agents can read them before calling `list_workflows`

package/docs/plans/workflow-source-setup-phase-1.md

@@ -0,0 +1,245 @@
+# Workflow Source Setup Phase 1
+
+This is the **canonical durable plan/design doc** for the near-term workflow-source setup initiative.
+
+Use it for:
+
+- the preferred phase-1 setup path
+- the core design boundaries that should remain true during implementation
+- migration and coexistence rules for legacy source setup
+- acceptance criteria for when phase 1 is done enough to build on
+
+Do **not** use this doc as a code-shadow full of exact APIs or step-by-step implementation recipes. Those should live in tickets, code, and tests.
+
+## Goal
+
+Make the common team-sharing path for workflows feel like **product setup**, not infrastructure wiring.
+
+Phase 1 should make it easy for a user to understand:
+
+- where team-shared workflows should live
+- how WorkRail discovers them
+- why they are visible
+- how this new path coexists with older setup paths during migration
+
+## Phase-1 product shape
+
+Phase 1 is:
+
+- **`Rooted Team Sharing`**
+- plus a **minimal `Source Control Tower`**
+
+That means:
+
+- explicit `workspacePath` on discovery-sensitive behavior
+- remembered workspace roots at user scope
+- recursive discovery of `.workrail/workflows/` under remembered roots
+- grouped source visibility
+- minimal provenance and precedence explanation
+- migration-aware guidance while legacy setup paths still exist
+
+## Why this is phase 1
+
+This path is the best near-term fit because it:
+
+- aligns with the platform vision already documented in `docs/plans/workrail-platform-vision.md`
+- reuses source metadata and discovery concepts already present in the codebase
+- improves the highest-frequency team-sharing path without requiring broad setup automation first
+- keeps the architecture explainable while the long-term source model is still being clarified
+
+## Non-goals for phase 1
+
+Phase 1 is **not**:
+
+- a generalized guided install flow for arbitrary third-party sources
+- the full canonical source catalog
+- a complete console/control-plane experience
+- final automation for remote/self-hosted auth setup
+- the final permanent ownership split for every `.workrail/*` file
+
+Those may follow later, but they are not required to make phase 1 useful and coherent.
+
+## Core user model
+
+The preferred team-sharing story should be simple enough to explain in plain language:
+
+- “Team workflows live in `.workrail/workflows/` in the repo.”
+- “This repo is registered as a workflow root once.”
+- “WorkRail discovers workflows from registered roots.”
+- “WorkRail can show which source made a workflow visible.”
+
+If the user still has to think in raw source kinds, env-var names, or storage internals for the common path, phase 1 is not simple enough.
+
+## Canonical phase-1 behavior
+
+### Team-shared workflows
+
+The preferred near-term convention is:
+
+- store team-shared workflows in repo-local `.workrail/workflows/`
+- allow nested/module-local `.workrail/workflows/` within remembered roots
+- rely on root registration instead of per-workflow source hookup
+
+### Workspace identity
+
+Discovery-sensitive tools should use **explicit `workspacePath`** as the trusted anchor.
+
+This initiative should continue the existing movement away from implicit server-process cwd behavior for workflow discovery and related operations.
+
+### Remembered roots
+
+WorkRail should remember repo/workspace roots at **user scope**.
+
+For phase 1, this remembered-root state is allowed to live in user-level `.workrail/` configuration, but the exact long-term ownership split of `.workrail/config.json` versus other `.workrail/*` artifacts remains intentionally unresolved.
+
+### Source visibility
+
+Users must be able to see enough information to trust the result:
+
+- which workflows are built-in
+- which came from remembered roots
+- which group/root made them visible
+- when multiple setup paths overlap, what precedence explanation applies
+
+Grouped visibility is part of the product, not polish.
+
+## Config ownership decisions for phase 1
+
+### Decided now
+
+- WorkRail should own the preferred rooted-sharing setup path under the `.workrail/` namespace.
+- User-level remembered roots are a valid phase-1 concept.
+- Repo-local `.workrail/workflows/` is the preferred team-sharing convention.
+- The system should avoid forcing users back to raw env configuration for the common path.
+
+### Intentionally not finalized yet
+
+- whether all user-level remembered-root state belongs in `~/.workrail/config.json`
+- whether repo-local metadata should live in repo `.workrail/config.json` or a separate artifact
+- how environment/capability cache state should be separated from source-setup state long-term
+
+Implementation should preserve this flexibility instead of baking in an overloaded single-file assumption.
+
+## Migration and coexistence rules
+
+Phase 1 must coexist with current setup behavior instead of pretending it does not exist.
+
+The doc and product should acknowledge these existing paths:
+
+- `./workflows`
+- `~/.workrail/workflows`
+- env-based source configuration such as custom storage paths, Git repos, registries, and plugins
+
+### Migration stance
+
+- keep existing paths working during transition
+- make the preferred rooted-sharing path unmistakable
+- use dual-read compatibility where needed
+- explain overlap rather than silently hiding it
+
+### Required explanation during migration
+
+When legacy sources and rooted-sharing both apply, the user should be able to understand:
+
+- which path is preferred going forward
+- which source currently made a workflow visible
+- what precedence rule resolved any overlap
+
+If WorkRail cannot explain this clearly, automation should not expand further.
+
+## Acceptance criteria
+
+Phase 1 is successful when all of the following are true:
+
+### User-facing outcomes
+
+- A user can set up team-shared workflows in **1–3 guided actions**.
+- A user can explain the model in plain language without naming env vars.
+- A user can tell the difference between built-in, personal, and repo-derived workflows.
+- A user can understand how the preferred rooted-sharing path relates to older setup paths.
+
+### Product/design outcomes
+
+- `workspacePath` is required anywhere discovery semantics materially depend on workspace identity.
+- Rooted discovery under remembered roots is available and reliable.
+- Source visibility is grouped enough to answer “where did this come from?”
+- Minimal precedence explanation exists for overlapping legacy and rooted sources.
+
+### Maintenance outcomes
+
+- Another maintainer can use this doc as the initiative entrypoint without needing the exploration notes first.
+- Follow-on tickets can be written from this doc without reopening the entire option space.
+
+## Recommended implementation slices
+
+These are the likely implementation slices for phase 1, in rough order:
+
+1. **Workspace anchoring**
+   - require and propagate `workspacePath` where discovery behavior depends on it
+2. **Remembered roots**
+   - persist user-level root registration in WorkRail-owned config
+3. **Rooted discovery**
+   - recursively discover `.workrail/workflows/` under remembered roots
+4. **Grouped visibility**
+   - expose source-aware workflow listing and inspection
+5. **Precedence and migration explanation**
+   - explain overlap with legacy setup paths
+
+This order matters more than exact file shapes.
+
+## Risks to guard against
+
+- **Config overload**: turning `.workrail/config.json` into a catch-all without a clear ownership model
+- **Hybrid-model confusion**: leaving old and new setup paths equally canonical for too long
+- **Invisible precedence**: making discovery broader without explaining why a workflow is visible
+- **Over-automation**: trying to automate cross-client setup before WorkRail can explain its own effective source state
+
+## Future phases
+
+This doc is still the canonical reference for **phase 1**, but the initiative should also be understandable beyond the first slice.
+
+### Phase 2 direction
+
+If phase 1 succeeds, the most likely next step is:
+
+- **`Guided Install + Canonical Source Catalog`**
+
+The goal of phase 2 is to make broader workflow hookup simpler across more source types without regressing explainability.
+
+Phase 2 likely includes:
+
+- a more explicit canonical source catalog owned by WorkRail
+- guided install flows for common third-party source types
+- clearer source health, update mode, and provenance reporting
+- a better-defined ownership split across user-global and repo-local `.workrail/*` configuration
+
+Phase 2 should **not** begin by bypassing the phase-1 visibility model. It should build on a trusted, explainable source model rather than trying to invent one in the installer itself.
+
+### Phase 3 and beyond
+
+Later phases may expand into:
+
+- richer control-tower / console visibility
+- portable workflow-pack or packaging conventions
+- broader install/distribution flows for community and cross-repo sharing
+- more opinionated management of remote and self-hosted source lifecycle
+
+These should be treated as follow-on opportunities, not implicit commitments.
+
+### Sequencing rule
+
+Future phases should continue to respect this order:
+
+1. make the effective source model visible and trustworthy
+2. make the common setup path simple
+3. expand automation and distribution breadth only after the model stays explainable
+
+If a later-phase idea weakens provenance, precedence clarity, or config ownership discipline, it should be considered out of sequence.
+
+## Companion docs
+
+- `docs/plans/workrail-platform-vision.md`
+- `docs/ideas/third-party-workflow-setup-design-thinking.md`
+- `docs/configuration.md`
+
+The design-thinking doc remains useful as exploration history, but this file is the preferred durable reference for the initiative’s near-term direction.