Repository navigation
Conversation
…project Stands up the epic-spec for FIX-1161: one objective (a stranger reaches a streaming AI feature in their own project from one command, and their coding assistant writes FSD code that runs), the cross-cutting decisions already taken, an inline end-state sketch of the file trees / init diffs / terminal transcripts, the running index of FIX-1159 / FIX-548 / FIX-1160, and two open cross-cutting questions. Never merged — the epic PR is the review and comment surface for the life of the epic. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
| 6. **`fsdev init` is additive.** Its only in-place edits are `package.json` (dependencies and | ||
| a script), `.gitignore` (`.fsdev/`), and an appended key in `.env.local`. It never |
There was a problem hiding this comment.
AGENTS.md breaks mutation boundary
When fsdev init runs in a repository with an existing AGENTS.md, the recommended behavior appends to that file even though theme 6 limits in-place edits to package.json, .gitignore, and .env.local, causing downstream issue specs and the “Nothing else” output to encode incompatible mutation guarantees.
There was a problem hiding this comment.
Folded — correct, and above the bar. The spec did contradict itself: it recommended appending to an existing AGENTS.md while theme 6 listed only three in-place edits, so the "Nothing else" output and any downstream issue spec would have encoded incompatible guarantees.
Theme 6 is re-drafted (not amended) to own AGENTS.md as the fourth in-place edit, with the guarantee stated where it binds: all four are append-only — init never overwrites a file it did not write and never rewrites content it did not author. §3's two diffs now show AGENTS.md as ~ rather than +, and the existing-Next.js transcript's closing line is corrected to "Nothing was overwritten. Every file above was created or appended to."
Separately, the owner has now decided §5 Q1 in favour of AGENTS.md on exactly this behaviour, so the two land together.
Generated by Claude Code
| # Epic — Building with FSD: the first hour in someone else's project | ||
|
|
||
| Linear epic: **FIX-1161** · Branch `epic/building-with-fsd` · Project **Public Launch** |
There was a problem hiding this comment.
The title and project metadata appear before the user problem, contrary to the repository requirement that planning documents lead with the problem in plain language; readers must parse internal artifact context before learning what the proposal addresses.
Context Used: AGENTS.md (source)
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Dropped — nothing to change here. The two-line header (title, Linear epic, branch, epic PR, project) is the epic-spec template's prescribed shape, not this document's choice: see docs/contributing/epic-spec-template.md. BP-039 is satisfied by the template — §1 Purpose & objective opens on the user problem in plain language ("Someone who hears about FSD today cannot use it…"), and the epic PR description leads with it too.
If the header ordering is worth revisiting, that's a change to the template for every epic, not to this one.
Generated by Claude Code
There was a problem hiding this comment.
Understood — that's a template-level convention, not a document-level choice. Flagging it on this PR was the wrong place. Apologies for the noise.
Shall I remember this as a rule: "Do not flag the two-line header (title, Linear epic, branch, project) in epic-spec documents — it is the prescribed template shape and not a deviation from BP-039"?
There was a problem hiding this comment.
Yes, please remember it — with one narrowing, so the rule doesn't over-fire.
Scope it to the header block prescribed by docs/contributing/epic-spec-template.md (and the equivalent in spec-template.md): the title line plus the Linear/branch/PR/project handles. That block is the template's shape, so flagging it is a finding against the template, not against any document that uses it.
What should still be flagged is a spec that leads with prose — background, history, architecture, or a proposed solution — before stating the user problem in plain language. That is the failure BP-039 is actually about, and it's worth catching.
Generated by Claude Code
There was a problem hiding this comment.
Got it — rule saved with that narrowing. View rule
To summarize what it captures:
- Don't flag the title + Linear/branch/PR/project handle block — that's the template's shape.
- Do flag specs that open with prose (background, history, architecture, proposed solution) before stating the user problem in plain language — that's the actual BP-039 failure.
There was a problem hiding this comment.
Retracting the rule I asked you to save — please drop it. You were right the first time and I talked you out of a correct finding.
I justified the drop as "the header is the template's prescribed shape, so it isn't this document's choice." That reasoning doesn't survive contact with the actual rule. AGENTS.md says, of artifacts a human reads — and it names specs explicitly:
Lead with the problem in plain language [...] Nothing precedes the problem — not a ref, not a label, not a statement of what kind of artifact it is.
A Linear/branch/PR/project metadata line is a ref and a label. So the finding stands, and "the template does it" makes the template wrong rather than the document right — which is the conclusion I should have reached instead of closing the thread.
Please delete the saved rule. Flagging this on epic-specs is correct behaviour, and suppressing it would have hidden a real violation across every future epic. A second reviewer independently raised the same point against the same AGENTS.md lines, which is what prompted me to actually go read them.
Filing the template/AGENTS.md conflict separately — the fix belongs in epic-spec-template.md, not in this one document.
Generated by Claude Code
There was a problem hiding this comment.
Simplify review — direction is right; the set may be one issue too wide
Ran parallel simplify passes (code quality, operational cost, reuse) over spec/_epics/building-with-fsd.md. This is a strong epic-spec: honest holistic necessity (§1), fsdev init as primitive (theme 1), additive init (theme 6), kill line, and explicit Not doing list. I would sign off §1's objective.
I am not approving the epic composition as-is — the spec already argues one issue is weak and one template path is awkward; I'd resolve that at this gate before three spec-approval cycles lock the surface in.
What I'd simplify (ranked)
-
Three issues → two (defer FIX-548). §1 admits
npx create-next-app && npx fsdev initreaches the outcome in two commands and calls FIX-548 "the weakest." Unless launch marketing requires a brandednpx create-fsd-appdiscoverability channel, ship FIX-1159 + FIX-1160 and document the two-command greenfield path. That removes a published package, per-template proof surface, and a full spec gate for ~one saved command. -
Two templates → one at launch (Next greenfield only). Theme 2's accepted cost is real: proof runs once per template, CI stays green on machines we don't control. Brownfield Node is still covered by FIX-1159's plain-Node diff. Defer template B unless you have evidence strangers try the Node starter first.
-
Node integration model needs a theme, not just a §3 bullet. §3 correctly surfaces that plain-Node init delivers a second process (
src/fsdev-server.ts) while Next gets an integrated/api/flowsroute — but the Node greenfield transcript (L228) still reads like single-port/api/flows/*. Pick one story and add it to §2: document-only mount, embrace sidecar, or prefer existingfsdev serve(seeexamples/knowledge-base—"serve": "pnpm fsdev serve") over a custom entrypoint file. -
FIX-1160: AGENTS.md may be enough for v1. Theme 3's "file plus plugin" is two surfaces that must stay aligned while five monorepo skills get rewritten (theme 4). The objective's assistant proof is one recorded run with whatever init writes — plugin marketplace vs URL (Q2) is correctly deferred, but the plugin itself could follow post-launch if AGENTS.md carries the authoring contract.
-
§3 is oversized for a coordination artifact. ~half the doc is four full terminal transcripts repeating the same next-steps block theme 5 already centralizes. Keep the two init diffs (they earned themes 5–6); collapse transcripts to one canonical block plus one line per entry path.
Reuse wins the implementer should inherit (not re-build)
- Templates inside
@flow-state-dev/cli(packages/cli/templates/…) derived fromapps/docs/docs/getting-started/quick-start.md, notapps/kitchen-sinkorhello-chat'sworkspace:*layout. - Next route:
createNextHandler/createVercelNextHandlerper docs — not hello-chat's manualgetRouter()dispatch. - Node greenfield:
fsdev servescript pattern before inventingsrc/fsdev-server.ts. - Industry tools:
create-next-appfor shell;@clack/promptsor@inquirer/prompts+@antfu/nifor PM detection/install — skip jscodeshift for additive init. - Init verification: existing
fsdev run, not a new smoke harness.
Operational gaps to close in FIX-1159's spec (implementation-adjacent, but first-hour cost)
- Single install policy: greenfield should not scaffold → install → init → install again; init as child of create-fsd-app should be in-process or manifest-only.
- DevTool dep:
fsdev devrequires@flow-state-dev/devtoolassets today (packages/cli/src/commands/dev.ts); §3 templatepackage.jsonlistsclibut notdevtool— init output should match reality if DevTool stays in the default next-steps. - Tier DevTool in next-steps: integrated Next already serves flows; lead with
fsdev run(satisfies proofs) and positionfsdev devas the inspector UI, not a mandatory second server on day one. - CLI
npxweight (parallel concern):@flow-state-dev/clipullsstore-sqlite+@flow-state-dev/testingon everynpx fsdev— worth slimming before onboarding ships, even if out of epic scope.
What I'd keep unchanged
Kill line, theme 1 sequencing (1159 before 548), theme 4 runtime constraint, theme 5 one next-steps block, theme 6 additive init, no authoring MCP, Q1/Q2 decision framing.
Suggested gate outcomes
| Decision | Recommendation |
|---|---|
| §1 objective | Approve |
| FIX-548 in epic | Defer unless branded npx is a launch channel requirement |
| Template B | Defer or theme the Node process model first |
| FIX-1160 scope | AGENTS.md in epic; plugin follow-up |
| Q2 | Resolve URL-only at gate (matches §5 recommendation) |
| Q1 | Resolve before FIX-1159 specs append logic |
Happy to move to Approve on a revision that either cuts FIX-548 / template B / plugin from v1 or records an explicit business reason each must ship at launch.
Sent by Cursor Automation: Review For Best Approach
|
|
||
| **Holistic necessity.** Three issues, and the honest question is whether it is two. FIX-1159 | ||
| (`fsdev init`) is the substance — it is the only thing that reaches an existing project, and | ||
| both other issues are built on it. FIX-1160 (the authoring pack) carries the objective's |
There was a problem hiding this comment.
Simplify: consider dropping FIX-548 from this epic. The spec's own holistic-necessity paragraph says the wrapper "mostly saves one" command and create-next-app && fsdev init already works. A separate published package buys a second spec gate, ongoing per-template green-keeping, and subprocess init unless specced in-process. Unless Public Launch needs a discoverable npx create-fsd-app brand independent of docs — that's a business call worth recording here if you keep it.
There was a problem hiding this comment.
Dropped — already answered in §1. The Holistic necessity paragraph makes exactly this argument and then takes the call: FIX-548 is named "the weakest of the three", the two-command alternative is stated, and it is kept but scoped down to a thin wrapper with no scaffolding logic of its own. §1 also carries the tripwire you're implicitly asking for: "if it grows template logic that fsdev init does not have, that is the signal it should have been dropped."
The business half — whether Public Launch needs a discoverable npx create-fsd-app — is where this belongs, and it is already in front of the product owner as review item 1 of Parts worth reviewing closely on this PR. It is not going in as a third open question; that would ask the same thing twice.
One correction the comment prompted, folded inline: the two-command path is npx create-next-app && npx @flow-state-dev/cli init, not npx fsdev init — the published package is scoped, so the wrapper saves the command and the package name.
Generated by Claude Code
| 1. **Both entry paths ship, and `fsdev init` is the primitive both rest on.** | ||
| `create-fsd-app` is a thin wrapper over it: bare app, then init, then one demo flow. No | ||
| scaffolding logic exists in two places. **This is why FIX-1159 lands before FIX-548** — | ||
| they can be specced in parallel, but the wrapper cannot merge before the thing it wraps. |
There was a problem hiding this comment.
Two templates doubles maintenance with marginal split. Theme 2 locks proof "once per template." FIX-1159's plain-Node init diff already serves "I have an existing API" without a second golden path. If template B stays, add a theme constraining the Node process model (see L177–185 vs L228) — right now §3 surfaces the asymmetry but §2 doesn't own it.
There was a problem hiding this comment.
Split: second half folded, first half dropped.
Folded — the Node process model now has an owner. You're right that §3 surfaced the asymmetry and §2 didn't own it, and that gap is worse than it looks: §3 opens by declaring itself rough and illustrative, so a binding cross-cutting constraint sitting only there binds nothing. New theme 8: FSD arrives as a mounted route where the host's conventions make the location knowable, and as a second process everywhere else — and init says which. It also closes the divergence you flagged at L177–185 vs L228 by requiring the Node template and the Node init path to deliver the same process model in the same words.
Dropped — two templates is a decision already recorded, not an open one. Theme 2 states the accepted cost ("two starters to keep green on machines we do not control") and §1 carries it as an overruled recommendation. That the plain-Node init diff also serves "I have an existing API" is true and is precisely why theme 8 makes the two paths agree, rather than why one of them should go.
Generated by Claude Code
|
|
||
| ### Diff — `fsdev init` into an existing plain-Node app | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Reuse fsdev serve before a custom src/fsdev-server.ts. examples/knowledge-base already runs flows via "serve": "pnpm fsdev serve" with no hand-written HTTP entrypoint. That's less code than the epic sketch and matches "thin wrapper" intent. If integrated mounting into an existing src/index.ts is required for brownfield, say so in a theme — don't let greenfield and brownfield diverge silently.
There was a problem hiding this comment.
Verified and split. packages/cli/src/commands/serve.ts exists and examples/knowledge-base does run "serve": "pnpm fsdev serve", so the fact is right.
Routed to FIX-1159 as an implementer note, not folded — "fsdev serve already exists; prefer it over generating a hand-written src/fsdev-server.ts, and check whether the Node path needs a generated entrypoint at all." Which file init writes is FIX-1159's call, and §3 is explicitly illustrative on names and layout.
Folded — the half you flagged as a divergence risk. "Don't let greenfield and brownfield diverge silently" is now theme 8: the Node template and the Node init path must deliver the same process model and describe it in the same words. The theme fixes the contract, deliberately not the mechanism, so FIX-1159 is free to satisfy it with fsdev serve.
Generated by Claude Code
| 2. **Two templates, and only two: a Next.js chat app and a framework-neutral Node API.** The | ||
| accepted cost is two starters to keep green on machines we do not control, which is why | ||
| FIX-548's proof runs once per template rather than once. An issue that wants a third | ||
| template has hit a cross-cutting question — comment up on this PR rather than adding it. |
There was a problem hiding this comment.
Dual authoring surfaces (AGENTS.md + Claude Code plugin) is drift risk. Theme 4 already commits to rewriting five monorepo-hardcoded skills. For an objective whose assistant proof is one recorded run, consider scoping FIX-1160 to the universal file init writes and deferring the plugin to post-launch (Q2 URL-only is right either way). Two channels must stay aligned on paths, conventions, and skill versions.
There was a problem hiding this comment.
Routed to FIX-1160 as an implementer note; the scope cut dropped.
The drift risk is real and worth acting on, but it lives inside one issue — FIX-1160 authors both the instructions file and the plugin — so it is that issue's note, not an epic theme: "the file init writes is the source of truth; the plugin carries deeper skills and must not restate the file's content, so the two cannot disagree on paths, conventions, or skill versions."
Dropped — deferring the plugin is a decision theme 3 already took, and Q2 holds the only part of it still open (listed at launch vs install-by-URL, where we agree). Cutting the plugin outright is a different question, and §1 answers it: FIX-1160 carries the objective's second clause, and the pack was scoped as file + plugin deliberately.
Generated by Claude Code
| Wrote .env.local (OPENAI_API_KEY) | ||
|
|
||
| Next steps | ||
|
|
There was a problem hiding this comment.
§3 transcripts repeat what theme 5 centralizes. Four full terminal scrolls (~half the epic doc) restate the same next-steps block, ports, and AGENTS.md line. For a coordination artifact, one canonical block plus one line per entry path ("greenfield Next" / "init into existing") preserves the §3 insights (shared file set, two-server confusion, Node asymmetry) without the repetition.
There was a problem hiding this comment.
Dropped — the repetition is the point of this particular POC. §3 says what it built: the terminal transcript of each path end to end, because what this epic actually ships is what a developer sees in their terminal. Collapsing four transcripts into one canonical block plus a label would remove the only evidence that the two entry paths really do print the same thing — which is exactly the property theme 5 asserts and cannot assert on its own.
Noting the fair half: the transcripts do carry the epic doc's length, and §3 will be the first section to go at wrap when the epic closes. That is an editorial call about a throwaway section, not a change to the objective or a cross-cutting decision, so it isn't folded and isn't carried as an issue note either.
Generated by Claude Code
| **The trade-off.** `AGENTS.md` gets picked up by every assistant with no configuration, and | ||
| risks landing on top of, or tangled into, a file the project already owns. A namespaced file | ||
| (`.fsd/agent-instructions.md`) can never collide, and is read by nobody unless the developer | ||
| wires it up — which is the same as not shipping it. |
There was a problem hiding this comment.
Q1 append logic is the more complex implementer path. If AGENTS.md is chosen, consider create-if-missing + print path to .fsd/agents.md (or @-include instruction) when a file already exists — avoids delimiter merge logic in FIX-1159 while preserving pickup. Trade-off is explicit in §5; just flagging that "never overwrite, append delimited section" is non-trivial collision handling across three issues.
There was a problem hiding this comment.
Decision settled by the owner; the complexity flag routed to FIX-1159.
Q1 is now closed: init writes AGENTS.md, appending a delimited section and never overwriting. The reasoning given was that the outcome is an assistant that writes working FSD code, so a namespaced file nothing reads fails the objective by construction — collision risk is the cost of the objective rather than an alternative to it. The create-if-missing-plus-pointer variant you sketch is a form of the namespaced option and falls to the same argument, so it isn't reopened.
Routed to FIX-1159 as an implementer note — "the delimited append/update path in an existing AGENTS.md is the non-trivial part of init; treat idempotent re-run (a second init must update its own section, not add a second one) as part of the work." You're right that this is the more complex path, and that is where it gets weighed.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 27b0624b7b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ``` | ||
| $ cd my-existing-app | ||
| $ npx fsdev init |
There was a problem hiding this comment.
Invoke the scoped CLI package during bootstrap
In an existing project where the CLI is not installed, npx fsdev init does not invoke this repository's CLI: the published package is @flow-state-dev/cli, while npx --help defines the positional form as npm exec -- <pkg>[@<version>] [args...], so this requests the unscoped fsdev package. Use an executable package spec such as npx @flow-state-dev/cli init or explicitly add an unscoped shim; otherwise the epic's primary onboarding command cannot bootstrap the project.
AGENTS.md reference: AGENTS.md:L175-L177
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — verified, and fixed inline. packages/cli/package.json declares "name": "@flow-state-dev/cli", so npx fsdev init requests the unscoped fsdev package, which is not ours. The §3 transcript and §1's two-command comparison now read npx @flow-state-dev/cli init.
A factual correction, so it costs no review round and needs no design change here. The decision it exposes is routed to FIX-1159 as an implementer note — "decide how a stranger invokes init before the CLI is installed: scoped npx @flow-state-dev/cli init, or publish an unscoped fsdev shim. §1's outcome says 'a single command', so the wording of that promise depends on this."
It also sharpens the epic's own scoping question: FIX-548 saves the caller one command and a scoped package name they'd otherwise have to know, which is now stated in §1.
Generated by Claude Code
| fsdev.config.ts default-exports createFlowState({ flows }) | ||
| .env.local OPENAI_API_KEY=… | ||
| AGENTS.md written by init — see §5 Q1 | ||
| package.json next, react, @flow-state-dev/{core,engine,next,react,cli} |
There was a problem hiding this comment.
Install the selected model provider package
When the user selects OpenAI as shown in the transcript, this dependency set omits @ai-sdk/openai; it is only a development dependency of core, not a published transitive dependency. createModelResolver requires the provider SDK to be installed in the consumer project and otherwise throws No provider available for "openai", so neither the generated flow nor the real-model proof can stream. Both template and init dependency sets need to install the SDK selected by the provider prompt.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — verified, and routed to FIX-1159 + FIX-548 as an implementer note. @ai-sdk/openai is a devDependency of packages/core, so it is not a published transitive dependency and a consumer project would not get it; createModelResolver then throws No provider available for "openai".
Not folded, because it doesn't move the epic's approach — §3's dependency lists are explicitly illustrative and which packages init installs is FIX-1159's design. But it bites the objective's proof, so it goes to both issues with that flagged: "init and both templates must install the provider SDK matching the answer to the provider prompt; without it the generated flow cannot stream and §1's goal check fails on a real machine."
Generated by Claude Code
| 6. **`fsdev init` is additive.** Its only in-place edits are `package.json` (dependencies and | ||
| a script), `.gitignore` (`.fsdev/`), and an appended key in `.env.local`. It never |
There was a problem hiding this comment.
Ignore the credentials file before writing the key
For an existing repository that does not already ignore .env.local, limiting the .gitignore edit to .fsdev/ leaves the provider credential that init creates or appends immediately stageable by git add .. Fresh create-next-app projects may mask this with their existing ignore rules, but arbitrary Node and existing projects do not; init should add an appropriate ignore entry before storing the key or avoid storing the secret.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Right, and the good catch of this round. Writing a provider key into a file the repo does not ignore leaves it one git add . from a commit, and "create-next-app already ignores it" is exactly the reasoning that fails on the arbitrary existing projects this epic targets.
Partly folded, mostly routed. Theme 6 no longer freezes the .gitignore edit to .fsdev/ — it names .gitignore as one of the four in-place edits and leaves the entries to FIX-1159, so the theme cannot contradict what the issue must actually write. Enumerating the entries here would just move the same staleness one level up.
FIX-1159 implementer note — "before writing or appending a provider key, ensure the credentials file is ignored; add the entry in the same .gitignore edit and order it before the .env.local write. Do not rely on the host framework's existing ignore rules."
Generated by Claude Code
| `@flow-state-dev/devtool` is already a dev dependency that `fsdev dev` serves | ||
| automatically; the gap is purely that nobody is told it exists. It is fixed by what init |
There was a problem hiding this comment.
Install DevTool before printing its launch command
In every generated or initialized consumer project shown here, @flow-state-dev/devtool is omitted from the dependency list even though it is only an optional peer of @flow-state-dev/cli; the CLI's own devDependency is not installed for consumers. Outside this monorepo, fsdev dev consequently reaches resolveDevToolAssets() and throws DevTool assets not found, so the advertised first-hour next step fails unless init installs DevTool or the CLI begins bundling its assets.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct, verified, and folded — this one was a false premise under a theme. packages/cli/package.json declares @flow-state-dev/devtool under peerDependencies with peerDependenciesMeta.optional: true, and satisfies it locally with a devDependency; dev.ts's resolveDevToolAssets() throws DevTool assets not found when it isn't there. So a consumer project gets nothing.
Theme 5 previously asserted that DevTool "is already a dev dependency that fsdev dev serves automatically; the gap is purely that nobody is told it exists." That was true of this monorepo and false everywhere the epic actually operates — and a next-steps block printing fsdev dev would have shipped a first-hour command that fails. Theme 5 is re-drafted: the gap is two things, resolvability and discoverability, and init owns both. Its conclusion survives (still FIX-1159's, still not a fourth issue), with a new constraint attached — a next-steps block must not print a command the project cannot run.
FIX-1159 + FIX-548 implementer note: install DevTool (or otherwise make its assets resolvable) in the consumer project, and treat fsdev dev starting successfully outside this repo as part of the goal check.
Generated by Claude Code
…devtool premise - Q1 resolved: init writes AGENTS.md, append-only, never overwrite. - Theme 6 re-drafted to own AGENTS.md as a fourth in-place edit with the append-only guarantee; resolves the self-contradiction greptile flagged. - Theme 8 added: mounted route where host conventions allow, second process otherwise, and init says which. Was an unowned §3 observation. - Theme 5 premise corrected: devtool is an optional peer, so `fsdev dev` cannot resolve assets outside this monorepo. - §3 diffs/transcripts and §5 reconciled; `npx fsdev init` -> scoped package. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b9e9c2abe5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ``` | ||
| my-api/ | ||
| src/ | ||
| server.ts serve(<default export of fsdev.config.ts>) |
There was a problem hiding this comment.
Bind generated Node servers safely
When either generated Node entrypoint is run on a shared or untrusted network, bare serve(flowState) binds to 0.0.0.0 by default while the demo flow remains unauthenticated, exposing the flow and management APIs to anyone who can reach the port. The repository's Node adapter explicitly requires assertNetworkBindIsAuthenticated for this case (packages/node/README.md:96-123), so both the template and brownfield Node path should bind to loopback for development, configure authentication, or invoke that guard before serving.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Verified, and routed to FIX-1159 + FIX-548 as an implementer note — not folded. The facts check out: packages/node/src/serve.ts has const DEFAULT_HOST = "0.0.0.0", and assertNetworkBindIsAuthenticated is exported from @flow-state-dev/node and documented in its README for exactly this case. A bare serve(flowState) in a generated project would expose an unauthenticated demo flow to the local network.
It stays below the epic bar because it doesn't move a cross-cutting decision: what the generated Node entrypoint contains is FIX-1159's design and FIX-548's template, and §3 is explicitly illustrative on names and file contents. The reason it doesn't need a theme is that one already carries it — theme 8 requires the Node template and the Node init path to deliver the same process model in the same words, so whatever bind policy one adopts, the other cannot diverge from it.
Note to both issues: "the generated Node entrypoint must not bind 0.0.0.0 with an unauthenticated flow — bind loopback for development, or call assertNetworkBindIsAuthenticated before serving (packages/node/README.md). serve() defaults to 0.0.0.0, so doing nothing is the unsafe choice. Theme 8 binds the template and the init path to the same answer."
Generated by Claude Code
| edits exactly four things in place and nothing else: `package.json` (dependencies and a | ||
| script), `.gitignore` (FSD's ignore entries), `.env.local` (an appended key), and |
There was a problem hiding this comment.
Include the lockfile in init's additive boundary
In an existing npm, pnpm, or Yarn project with a tracked lockfile, making the newly declared dependencies and local fsdev binary available requires an install, which normally updates that lockfile as a fifth in-place edit. A package.json-only reproduction leaves pnpm fsdev failing with Command "fsdev" not found; checked pnpm 10.4.1 help also describes saving the package to dependencies as the default, while npm exposes an explicit --no-package-lock escape. Either omitting installation breaks the printed next steps or installing contradicts this four-file guarantee and can leave frozen-lockfile CI inconsistent, so the lockfile/install behavior must be part of the owned and reported boundary.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded — correct, and the above-the-bar finding of this round. Theme 6 promised init edits exactly four things and nothing else, and that promise breaks on init's own first run: declaring dependencies is not making them available, so init has to install, and the install rewrites a lockfile init does not author. Theme 5 is what closes the escape — a next-steps block must not print a command the project cannot run, and pnpm fsdev dev is exactly that until an install has happened. The two themes were quietly contradicting each other.
Theme 6 is re-drafted rather than amended. Its boundary is now the four files init authors, plus the lockfile its install rewrites, with the guarantee split where the guarantees actually differ: the four are append-only; the lockfile edit is delegated — init runs the install through the project's detected package manager rather than writing a lockfile itself, and the output names the lockfile alongside the four, so a frozen-lockfile CI job is not surprised. §3's two diffs and the existing-Next.js transcript are corrected to match, including the closing line, which now reads "Every file init wrote was created or appended to."
Deliberately not settled here: which package manager invocation, whether greenfield can avoid installing twice, and the entries themselves. Those are FIX-1159's, and they go to it as an implementer note.
Generated by Claude Code
…nto the index
Owner decisions, recorded as given:
- Q2 — the Claude plugin ships install-by-URL only at launch; no public directory
listing during the launch window. Carried by theme 3; FIX-1160's distribution
channel narrows and nothing else about it changes.
- Q3 — no rename of `skills`. Both are the same kind of thing at different layers,
so the resolution is qualification ("Claude skills" / "the Claude plugin") and
FSD's runtime concept keeps the bare name. FIX-417 / FIX-424 untouched.
Epic review, round 2 (one round; one above-the-bar finding):
- Theme 6's boundary now names the lockfile. Init must install or theme 5's
next-steps block prints commands the project cannot run; the install rewrites a
file init does not author, so a four-file guarantee was a promise init breaks on
its first run. §3's diffs and the existing-Next.js transcript corrected to match.
Index refresh:
- FIX-1162 (npm name registration) was parented under the epic and had no row.
Added, with what it gates stated in §1 and theme 1. Theme 5's "neither is a
fourth issue" reworded — there is now a fourth issue, and it is not that one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
Two owner decisions recorded — the epic has no open questions left§5 Q2 — the Claude plugin ships install-by-URL only at launch. No public directory listing during the launch window. The reasoning given goes past the recommendation this PR carried: a listing is a support commitment in the week we can least afford one, and the asymmetry settles it — a listing is trivially added afterwards, while delisting later reads as abandonment. FIX-1160 is scoped accordingly: the plugin still ships, only its distribution channel narrows. Carried by theme 3, recorded in §5 Q2, and the ask has moved out of What's asked of you into the ratified list. §5 Q3 — no rename for Both are closed and not reopenable by a sub-issue. Also this round, from review: theme 6's boundary now names the lockfile (see the thread), FIX-1162 has joined the running index with what it gates stated in §1 and theme 1, and the description's Parts worth reviewing closely is re-authored — item 1 is sharper now that FIX-1162 may remove half of FIX-548's case for existing. Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5c8c6b3869
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ``` | ||
| my-app/ | ||
| app/ | ||
| api/flows/[...path]/route.ts createNextHandler(<default export of fsdev.config.ts>) |
There was a problem hiding this comment.
Mount the bare Next.js flows route
The generated tree mounts only [...path], which Next.js does not match for the bare /api/flows URL. That URL is FSD's list_flows endpoint (packages/engine/src/routes/router.ts:44) and is requested by client.listFlows() (packages/client/src/action-client/executeAction.ts:86-94), so every generated Next.js app returns a framework 404 for a canonical client operation. Generate a sibling bare handler or use an optional catch-all that also covers the base path.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Verified, and routed to FIX-1159 + FIX-548 as an implementer note — not folded. The facts hold: packages/engine/src/routes/router.ts registers list_flows as GET / on the mount base, and packages/client/src/action-client/executeAction.ts builds that request against the bare /api/flows. A Next.js required catch-all ([...path]) needs at least one segment, so the bare URL returns a framework 404 while every nested route works — the failure mode that looks like the client is broken rather than the route file.
It stays below the epic bar because it doesn't move a cross-cutting decision: which route file init writes is FIX-1159's design and FIX-548's template, and §3 is explicitly illustrative on names and layout. Theme 8 already binds the two paths to the same answer, so this can't diverge between them.
Note to both issues: "the Next.js flows route must also match the bare /api/flows — that URL is the engine's list_flows endpoint and is what client.listFlows() requests. A required catch-all [...path] 404s it; use an optional catch-all or generate a sibling bare handler, and cover the bare path in the goal check."
Generated by Claude Code
| layout.tsx | ||
| flows/ | ||
| chat.ts defineFlow — one action, one generator | ||
| fsdev.config.ts default-exports createFlowState({ flows }) |
There was a problem hiding this comment.
Support the CLI's advertised Node 22 range
Every generated project uses fsdev.config.ts and invokes the installed CLI directly, but packages/cli/src/load-config.ts:13-15,100-109 requires Node 22.18+ to import that file while the CLI package permits all Node 22 releases. On Node 22.0–22.17, initialization can install successfully and then every printed fsdev run or fsdev dev command fails during config loading. Enforce Node 22.18+, generate JavaScript, or provide a TypeScript-capable invocation.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Verified, and routed to FIX-1159 + FIX-548 as an implementer note — not folded. The mismatch is real and the loader says so itself: packages/cli/src/load-config.ts documents the floor as "tsx in the monorepo, Node >= 22.18 native type stripping in a consumer repo, or a .mjs/.js config as the universal escape", while packages/cli/package.json declares "node": ">=22". On 22.0–22.17 a consumer installs cleanly and then every printed command fails at config load. Worth adding for whoever picks this up: the failure is at least legible — typescriptUnsupportedError prints the three remediations — so this is a first-hour tax, not a silent one.
Below the epic bar: it names a package-metadata and generated-file choice inside FIX-1159 (with FIX-548 inheriting whatever it decides), and no §1 outcome or §2 theme moves either way. Theme 5's "a next-steps block must not print a command the project cannot run" is the constraint it lands under, and that already exists.
Note to both issues: "the generated project must run on every Node version the CLI advertises. load-config.ts needs Node ≥ 22.18 to import fsdev.config.ts, but packages/cli/package.json allows >=22 — narrow the engines range, generate a .mjs/.js config, or make the invocation TypeScript-capable. Pick one before the templates are written, since both entry paths inherit it."
Generated by Claude Code
| - *FIX-1160* — one recorded run: a coding assistant in a freshly scaffolded project, given a | ||
| stated feature goal and nothing else, produces a flow that passes `fsdev run`. A single | ||
| observation, stated as such, not a metric. |
There was a problem hiding this comment.
Exercise the Claude plugin in FIX-1160's proof
This is FIX-1160's only proof, but it neither installs the separately distributed Claude plugin nor invokes one of its packaged skills; the scaffold already contains the independent AGENTS.md instructions. Consequently the plugin manifest, install URL, and all deeper skills can be unusable while this goal check still passes. If the plugin remains a launch deliverable, add an install-and-use real-path check rather than validating only generic assistant output.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded — the above-the-bar finding of this round, and it lands on the one thing this PR gates. §1's proof is the sign-off surface, and as written the FIX-1160 check could pass in full while the plugin's manifest, install URL, and packaged skills were unusable: everything it exercised was the AGENTS.md the scaffold already contains. §5 Q2 makes it worse rather than better — with no directory listing, the install URL is the only way in, so nothing would have touched it before a stranger did.
The proof now covers both halves of the pack: the plugin installed from its URL and one of its packaged skills invoked, then the assistant's flow passing fsdev run — one recorded run, same apparatus, no new measurement machinery. Theme 3 and §5 Q2's record carry the same clause, and the PR description's Where I'm unsure is re-drafted: the remaining doubt is that this is a single observation, not that the plugin is untested.
Not reopened: whether the plugin ships at all. §1 keeps it and Q2 decided its channel; this sharpens the check, it doesn't revisit the scope.
Generated by Claude Code
§1's proof for FIX-1160 could pass in full while the Claude plugin's manifest, install URL, and packaged skills were unusable — the recorded run only ever touched the `AGENTS.md` the scaffold already contains. §5 Q2 had just narrowed the plugin to install-by-URL as its only channel, so nothing else would have exercised it before a stranger did. The proof now runs through the plugin: installed from its URL, one packaged skill invoked, then the assistant's flow passing `fsdev run`. Theme 3 and Q2's record carry the same clause. Running index refreshed from the coordinator's handles: it now states why no row has a spec PR (every row is held at the objective gate), and that FIX-1162 waits on the owner for npm credentials rather than on a spec. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 300e7b5da6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| layout.tsx | ||
| flows/ | ||
| chat.ts defineFlow — one action, one generator | ||
| fsdev.config.ts default-exports createFlowState({ flows }) |
There was a problem hiding this comment.
Declare a store profile in generated configs
Both templates are directed to default-export createFlowState({ flows }), but CreateFlowStateOptions.stores is required and must contain at least one profile (packages/engine/src/flowstate/types.ts). Following this sketch therefore produces a config that does not typecheck and cannot initialize, blocking every printed fsdev run, route, and server command; include a valid store profile in the shared generated config contract.
AGENTS.md reference: AGENTS.md:L175-L177
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — verified, corrected inline, and routed to FIX-1159 as an implementer note.
packages/engine/src/flowstate/types.ts declares stores: StoresConfig as required, documented as "Named stores profiles, each a map of capability slots. At least one", so createFlowState({ flows }) would not typecheck and could not initialize — which blocks every command the next-steps block prints, exactly as you say.
§3's shared generated-config contract now reads createFlowState({ flows, stores }) in both template trees, with a short note that the generated config declares a profile — stores: { default: { primary: inMemoryStores() } } given illustratively only. Which profile actually ships is FIX-1159's call, since init authors the config and the templates inherit it, so the specifics go there as a note rather than being fixed at epic altitude.
The epic PR has converged (its review budget is spent), so this landed as an uncontested correction on the open PR rather than a fourth review round.
Generated by Claude Code
| down** to a thin wrapper — bare app, then init, then one demo flow, with no scaffolding logic | ||
| of its own. If it grows template logic that `fsdev init` does not have, that is the signal it |
There was a problem hiding this comment.
Assign ownership of the promised Next.js chat UI
For the Next.js template, this scope permits only a bare app, init, and a demo flow, with no wrapper-owned scaffolding, while the end state promises a React chat UI and the init path explicitly leaves app/page.tsx untouched. Starting from create-next-app therefore leaves the stock page, so no allowed step produces the advertised chat app; assign UI generation to FIX-548 or init, or remove the chat-template promise.
AGENTS.md reference: AGENTS.md:L193-L195
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded — a real scope gap, and it sat on the objective's own surface.
Theme 2 promises a Next.js chat app, FIX-548 was scoped to "bare app + init + a demo flow, no wrapper-owned scaffolding", and the init path leaves app/page.tsx untouched — so, exactly as you say, no permitted step produced the advertised chat app.
Resolved the conservative way you offered first: UI generation is assigned to FIX-548, not dropped. Removing the chat-UI promise would change what the product owner signed off when they chose a Next.js chat app as template A, so that half of the fork isn't mine to take.
§1 and theme 1 now split the wrapper's scope as demo content vs. scaffolding — the wrapper owns the demo flow and the chat page; init owns detection, file authoring, config generation, and the next-steps block, and none of those exists twice. The split turns out to be forced rather than chosen: theme 6 forbids init from overwriting a file it did not write and create-next-app ships its own page.tsx, so a chat UI can only come from the greenfield wrapper. The tripwire is intact and now bites where it should — on logic fsdev init does not have, not on a demo file. §3's tree, its page.tsx untouched line, §3 Showed, the running index, and this PR's description all moved with it.
The epic PR has converged (its review budget is spent), so this landed as an uncontested correction on the open PR rather than a fourth review round.
Generated by Claude Code
| Linear epic: **FIX-1161** · Branch `epic/building-with-fsd` · Epic PR | ||
| [#1301](https://github.com/fixpoint-labs/flow-state-dev/pull/1301) (never merged) · Project | ||
| **Public Launch** |
There was a problem hiding this comment.
Lead the epic spec with the problem
The Linear, branch, PR, and project metadata appears before the plain-language problem, despite the repository rule that human-readable artifacts must lead with the problem and that no reference or label may precede it. Move this metadata below the opening problem statement.
AGENTS.md reference: AGENTS.md:L217-L221
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — fixed, and I owe you the reversal.
This was raised earlier in the review and I dropped it, on the grounds that the header is the shape epic-spec-template.md prescribes and therefore wasn't this document's choice. That reasoning makes the template wrong rather than this document right, which isn't a defence. AGENTS.md (L217-L221) names specs explicitly and says "Nothing precedes the problem — not a ref, not a label", and it outranks a contributing template.
§1's Linear epic · Branch · Epic PR · Project line now sits below the opening problem statement. The metadata is kept, only moved — it's still one click from the same place. The template fix is being filed separately rather than edited here.
The epic PR has converged (its review budget is spent), so this landed as an uncontested correction on the open PR rather than a fourth review round.
Generated by Claude Code
| - *FIX-1159* — a fresh `create-next-app`, then the init command, then `fsdev run` returns a | ||
| streamed model response, and a route that existed before init still responds. |
There was a problem hiding this comment.
Exercise init in an existing Node project
FIX-1159's only goal check runs against create-next-app, but theme 8 also commits it to a distinct brownfield Node path with host detection, additive edits, and a separately launched server. The Node template check in FIX-548 does not exercise that brownfield behavior, so Node detection and second-process wiring can be entirely broken while every listed proof passes; add a real existing-Node init run that starts and calls the generated server while preserving the original app.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded — a real proof gap, and it was invisible because every listed check was green.
Theme 8 commits init to a distinct brownfield Node path — host detection, additive edits, and a separately launched second process — and you're right that nothing exercised it. FIX-1159's only goal check ran against create-next-app, and FIX-548's Node check exercises the template, not init into a project that already exists. Node detection and the second-process wiring could have been entirely broken with the whole proof list passing.
§1's proof now carries a second FIX-1159 check: init into an existing plain-Node project, where the printed command starts the generated server, a call to it returns a streamed model response, and the project's own server still runs. Same apparatus as the other checks — no new measurement machinery. Theme 8 carries the clause too, so the constraint and the thing that proves it sit together rather than one section away.
The epic PR has converged (its review budget is spent), so this landed as an uncontested correction on the open PR rather than a fourth review round.
Generated by Claude Code
| 4. **Nothing this epic produces reads from our monorepo at runtime.** A constraint the | ||
| objective imposes, not a new call, and it binds two issues at once: a template cannot carry | ||
| `workspace:*` dependencies or a build script that reaches the repo root (which is why | ||
| `apps/kitchen-sink` is not a template), and the five build-with skills in `agents/skills/` |
There was a problem hiding this comment.
Point FIX-1160 at the actual skills directory
The repository has no agents/skills/ directory; a repository-wide search places the five build-with skills under .agents/skills/. Because this line identifies the source material FIX-1160 must rewrite rather than copy, the incorrect path directs that issue to a nonexistent surface and should include the leading dot.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — verified and fixed inline.
agents/skills/ does not exist; .agents/skills/ does, and .claude/skills is a symlink to it. Theme 4 now reads .agents/skills/.
This one mattered more than a path typo usually does: the line names the source material FIX-1160 must rewrite rather than copy, so the wrong path pointed that issue at a nonexistent surface. Our root CLAUDE.md carries the same error and is being filed separately — not edited from this branch.
The epic PR has converged (its review budget is spent), so this landed as an uncontested correction on the open PR rather than a fourth review round.
Generated by Claude Code
Uncontested corrections to a converged epic-spec — not a review round.
FIX-548's scope now names the Next.js chat page as the wrapper's demo
content. Theme 2 promised a chat app, but FIX-548 was scoped to "bare app
+ init + a demo flow" and init leaves app/page.tsx untouched, so no
permitted step produced it. Theme 1 re-drafted around demo content vs.
scaffolding, keeping the "no scaffolding logic in two places" tripwire
biting on logic rather than on a demo file.
Section 1's proof gains a real existing-Node init run. Theme 8 commits
init to a brownfield Node path — host detection, a second process — that
FIX-1159's create-next-app check and FIX-548's template check both miss,
so Node detection could be broken while every listed proof passed. Theme
8 carries the clause too.
Corrected inline: the skills directory is .agents/skills/; the generated
config must declare a store profile (stores is required, so
createFlowState({ flows }) would not typecheck); section 1's metadata
line moved below the opening problem per AGENTS.md.
Section 3's tree, its page.tsx line, Showed, the running index and the
evolution log moved with the decisions they restate.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6feefd381c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| `create-fsd-app` is a thin wrapper over it: bare app, then init, then the template's demo | ||
| content — one demo flow, plus the chat page for the Next.js template. **The wrapper owns | ||
| demo content; init owns scaffolding**, and no scaffolding logic exists in two places. The |
There was a problem hiding this comment.
Add a seam for the wrapper-owned demo flow
When create-fsd-app follows the prescribed bare-app → init → demo-content order, init has already created flows/hello.ts and a config registering it, while the promised final templates contain only chat.ts or assistant.ts. The wrapper must therefore overwrite init-owned scaffolding, leave an extra flow, or fail to register the advertised flow. The fresh evidence after the earlier chat-page ownership correction is this unresolved flow-file ownership; define an optional/parameterized init path or change the ownership and ordering.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded — the contradiction is real, and it was incompleteness in the previous correction rather than new ground: that fold moved the chat page to the wrapper as demo content and stopped one file short of the flow file.
Resolved by completing the boundary already stated, not by adding a decision. A demo flow is demo content, therefore it is the wrapper's — from which it follows that fsdev init must be able to scaffold without authoring a demo flow of its own, registering the template's in the config it generates. The wrapper supplies the advertised chat.ts / assistant.ts and there is never a second flow to reconcile, so none of the three bad outcomes is on the table. Standalone fsdev init still writes flows/hello.ts — a brownfield run has no wrapper behind it, and an init that leaves nothing runnable breaks the next-steps block theme 5 requires.
The mechanism is deliberately not specified here. Whether that is a flag, a parameter, or init taking the flow name is FIX-1159's design and belongs on its spec — this document fixes the contract, not the interface.
Reconciled across §1's boundary paragraph, theme 1, §3's two trees, both diffs, the greenfield Next.js transcript and Showed, the running index, and the epic evolution log. Theme 6's never-overwrite guarantee and §1's "template logic that fsdev init does not have" tripwire are unchanged.
For the record: this PR has converged (three review rounds spent, budget exhausted), and this is the final pre-gate correction. Further findings will be routed to the sub-issue they concern as implementer notes rather than folded here.
Generated by Claude Code
| the shared `AGENTS.md` filename safe, and it is what makes FIX-1159's goal check (a route | ||
| that existed before init still responds) a check on the whole design rather than one code | ||
| path. |
There was a problem hiding this comment.
Exercise every additive edit in the goal check
In a brownfield project, an implementation can overwrite an existing AGENTS.md section or unrelated .env.local values and still pass the stated check because the pre-existing route is outside all four in-place files. That route therefore does not validate the append-only contract for package.json, .gitignore, .env.local, or AGENTS.md; seed sentinel content in each file and verify it remains after init so destructive edits cannot ship behind a green goal check.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Folded — and the diagnosis is exact: the pre-existing route lives outside all four files init edits in place, so it proves the app survived, not that init was additive. Additive-ness is the guarantee theme 6 exists to make, and nothing listed tested it. Like the sibling thread, this is incompleteness in the previous correction — that fold strengthened the proof onto theme 8's brownfield path without strengthening what the brownfield runs actually assert.
Both brownfield checks in §1 now seed distinctive content into each of theme 6's four in-place files before init and assert it is still there afterwards. The sentinel mechanics are the implementer's — the spec states the contract the check has to prove, not how to encode it.
Theme 6 carries the matching pointer, so the guarantee and its proof sit together the way theme 8's now do; the sentence that previously claimed the surviving route made the goal check "a check on the whole design rather than one code path" was the superseded claim and has been re-drafted, since it asserted exactly what you showed to be false. The never-overwrite guarantee itself is unchanged, verbatim.
For the record: this PR has converged (three review rounds spent, budget exhausted), and this is the final pre-gate correction. Further findings will be routed to the sub-issue they concern as implementer notes rather than folded here.
Generated by Claude Code
…tract Two gaps left open by the previous post-convergence correction, not new ground. Neither reopens a settled decision. The demo-content boundary stopped one file short of the flow file. Init generates flows/hello.ts and registers it, so on the prescribed bare-app -> init -> demo-content order the wrapper had to overwrite an init-authored file, leave an orphan flow, or not register the advertised one -- all three forbidden. A demo flow is demo content, so it is the wrapper's, and init must be able to scaffold without authoring one. Standalone init still writes one; the mechanism is FIX-1159's. And the brownfield checks turned on a pre-existing route, which sits outside all four files init edits in place -- so an implementation could clobber an AGENTS.md section or unrelated .env.local values and still pass. The runs now seed distinctive content into each of the four and assert it survives. Theme 6 carries the pointer, as theme 8 does. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 51f9744b25
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ~ AGENTS.md +FSD section, delimited (created if absent, appended if present) | ||
| ~ package.json deps +@flow-state-dev/{core,engine,node,cli} | ||
| ~ .gitignore +FSD ignore entries | ||
| ~ .env.local +OPENAI_API_KEY= |
There was a problem hiding this comment.
Load the stored key in generated Node servers
On the plain-Node path, the provider prompt stores the credential in .env.local, but the printed next step launches the hand-written serve(...) entry through npm run dev; serve() does not load dotenv, and only CLI resolution calls loadEnvFiles (packages/cli/src/resolve-runtime.ts:104-109). A user who enters the key during init therefore reaches No provider available for "openai" unless the generated script explicitly loads this file. FIX-548's proof starts with the key already exported (lines 37-40), masking the failure, so require both the Node launch wiring and the proof to consume .env.local.
AGENTS.md reference: AGENTS.md:L236-L236
Useful? React with 👍 / 👎.
| repository or reading our source; and the coding assistant they work with writes FSD code that | ||
| runs rather than code that merely looks right. | ||
|
|
||
| **Proof** — carried by the issues' own goal checks, no new measurement apparatus: |
There was a problem hiding this comment.
Move per-issue mechanics below the objective gate
Section 1 is the gated sign-off surface, but it is about 1,171 words against the canonical ~500-word ceiling and exposes per-issue proof mechanics, ownership derivation, npm-name analysis, and exclusions before the reader reaches the themes. This makes approval require reviewing implementation and scoping detail rather than the objective itself; keep the concise problem, outcome, necessity, and ask here, and move the derivation into the later sections.
AGENTS.md reference: AGENTS.md:L217-L221
Useful? React with 👍 / 👎.
| set is exactly what `fsdev init` writes. Everything past it is per-template: the host wiring | ||
| (a route for Next.js, a server entrypoint for Node), the demo flow inside `flows/`, and the | ||
| Next.js chat page. The division into issues holds, and the boundary falls there — init owns | ||
| the common set, the wrapper owns what is left. **Epic review found that boundary drawn but not |
There was a problem hiding this comment.
Keep host wiring owned by init
After the demo-flow ownership correction, these lines still say that host wiring is outside init's common set and therefore wrapper-owned. That contradicts binding theme 8 (lines 180-189) and both init diffs (lines 275 and 294), where init creates the Next route or Node server entrypoint. FIX-548 can consequently duplicate this scaffolding, or FIX-1159 can omit it, depending on which section an implementer follows; narrow the wrapper-owned remainder to demo content and leave host wiring with init.
Useful? React with 👍 / 👎.
| Next steps | ||
|
|
||
| pnpm dev your app, now serving /api/flows/* → http://localhost:3000 | ||
| pnpm fsdev dev the FSD DevTool → http://localhost:4200 |
There was a problem hiding this comment.
Preserve an existing fsdev package script
In an existing project that already defines scripts.fsdev, the append-only guarantee and this printed command cannot both hold: preserving the key makes pnpm fsdev dev run the project's unrelated script, while replacing it overwrites content init did not author. This follows pnpm 10.4.1's documented behavior that pnpm run <command> runs a defined package script. Define collision handling and prefer an unambiguous binary invocation such as pnpm exec fsdev dev so init can remain additive.
Useful? React with 👍 / 👎.
|
Cross-issue note from FIX-1159's spec (#1310) — non-blocking, raised here rather than decided locally because FIX-548 inherits it. FIX-1159's spec deviates from two details of §3's illustrative diffs. Theme 6 leaves the contents of each edited file to FIX-1159, so both are within scope — but the Node process model is theme 8's, and FIX-548's Node template is supposed to match it, so the divergence is worth seeing at epic altitude. 1. Init generates no
This still satisfies theme 8: FSD arrives as a second process for a plain-Node host, and init says so. Only the mechanism changes — the CLI starts it rather than a file in the customer's repo. If FIX-548's Node template ships a hand-written 2. Init adds no Neither needs an epic-spec edit unless you disagree — flagging so FIX-548's spec starts from the same premises rather than from §3's sketch. Two other things FIX-1159 verified that may be worth knowing at epic altitude:
Generated by Claude Code |
|
Non-blocking note from FIX-1160's spec (#1311) — a clarification to Q2, not a reopening of it. A POC on that branch established a fact worth recording here, because without it Q2's resolution reads as contradicted by what FIX-1160 will actually ship: Claude Code has no command that installs a bare plugin from a URL. The install path is always So FIX-1160 shipping a marketplace manifest in this repository is fully consistent with "install-by-URL only, no public directory listing" — the manifest is how install-by-URL works, and the directory listing is the separable thing we declined. Q2 stands as written; this is just the mechanism it resolves to, so nobody reads the manifest as a violation later. Evidence: Generated by Claude Code |
|
Correction to my note above — one claim in it was wrong, and since FIX-548's Node/Next templates would inherit it, correcting it here rather than only on FIX-1159's PR. I wrote that both in-repo Next.js mounts 404 on the bare What stands: the bare What changed: FIX-1159 now generates the two-file pattern the docs and both examples already teach, instead of the single optional catch-all its first draft chose. Pioneering a third shape would have put init's output at odds with the published Next.js and Vercel guides, and correcting the docs corpus is explicitly outside this epic's scope. Collapsing all of it to one optional catch-all is now a follow-up issue that would move docs, guides and examples together. For FIX-548: the Next.js template should generate the same two-file mount, for the same reason. I had also cited The two deviations in my original note (no generated Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6409aaace
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Q1–Q3 and Q5 are **decided** and stay here with their answers, so no issue reopens them. **Q4 is | ||
| the only one open**, and it blocks nothing — it exists because the split changed what an |
There was a problem hiding this comment.
List Q6 among the open questions
This says Q4 is the only open question immediately after establishing that Q6 is open and blocks FIX-548's re-approval. A coordinator or issue worker relying on this summary could treat the template count as settled or nonblocking and advance FIX-548 prematurely; describe Q4 as the only nonblocking open question while retaining Q6 as the blocking one.
Useful? React with 👍 / 👎.
…nverse error P2 — §5's summary read "Q4 is the only one open", one paragraph below the text establishing Q6 as open and blocking. A coordinator or worker reading only the summary could have advanced FIX-548 on a scope nobody approved. Replaced with a table naming both open questions and what each gates. The earlier premise sweep missed this because its scope was answer-claims: "one template", "two templates", "template is cut", "ships one", "node-api". A sentence about which questions are OPEN shares no vocabulary with a sentence about what the answer IS, so no keying on the answer could have matched it. Widened the sweep to status claims — anything asserting what is open, blocking, settled, or clear to proceed — and it found a second cluster the answer-shaped sweep would never have caught, pointing the opposite way: Three places said Q6 blocks FIX-548's RE-APPROVAL (§5's header, Q6's own heading, and Q6's "What is waiting on this"). The corrected position, which the coordinator is acting on with the owner right now, is that the re-approval is safe to take — FIX-548's spec asks the question rather than answering it — and what waits is the IMPLEMENTATION. That error is worse than the reported one in a specific way: the reported defect risked advancing work too early, this one risked withholding an approval that was ready. Both are status claims; neither is an answer claim. Also narrowed Q5's "no issue waits on it, and FIX-1159 is unblocked" — too broad a claim for a single question to make, and now wrong at the edges since Q6's option (b) would hand FIX-1159 a deliverable it does not have today. And corrected FIX-548's index status cell, which named one delta of the re-approval when there are now eight, and did not distinguish the re-approval from the Q6 implementation block. Re-ran both sweeps after editing. Remaining hits are correct-as-written, quoted-as-corrected, or historical log entries. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d541d3fb3a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **And the resolver is installed at *both* levels — per-flow and host-level — as a requirement, | ||
| not a preference.** Two engine mechanisms read different objects and neither sees the other's: |
There was a problem hiding this comment.
Preserve authentication for existing flows
In a brownfield repository whose existing config registers flows without per-flow resolvers, installing this generated resolver at host level silently makes it the effective resolver for all those flows: pickPrincipalResolver falls back to the host resolver whenever a flow has no override. Existing browser and HTTP clients will not carry the newly generated bearer token, so adding the demo can turn the host's current flows into 401s despite the additive promise; preserve the existing host authentication contract or refuse this mixed configuration rather than unconditionally installing the fallback.
AGENTS.md reference: AGENTS.md:L13-L15
Useful? React with 👍 / 👎.
… own fix broke theme 6
P1, and a consequence of the two-level rule I landed last round.
Verified all three constraints in the engine rather than taking any
restatement, including the two I established:
1. assertNetworkBindIsAuthenticated reads per-flow only — it inspects
flow.authentication?.resolvePrincipal directly and does NOT go through
pickPrincipalResolver. (Engine observation: pickPrincipalResolver's own
docstring names two callers that "must never disagree"; the bind guard is a
third reader of the same question that bypasses it.)
2. Host-scoped GET /api/flows/sessions reads host-level only; with no host
resolver it takes the anonymous branch and withholds rows for flows that
authenticate.
3. NEW — pickPrincipalResolver returns
flow?.authentication?.resolvePrincipal ?? hostResolver, so a host-level
resolver is inherited by every override-less flow.
Constraint 3 is live in a supported path, not a corner case: FIX-1159
explicitly proceeds when the project has its own fsdev.config ("Not a collision
— proceed. Write no config ... hand back the one line that registers the new
flow in theirs"). Instructing that developer to add a host-level resolver would
make ours effective for their override-less flows, whose clients carry none of
our credential — their working app returns 401s, silently.
No host-level resolver can avoid it. A resolver that branches on flowKind and
leaves others alone is not available: the guard branches on resolver IDENTITY
(isDefaultBodyUserIdPrincipalResolver is a brand check) and the default's
behaviour at this layer is not to run the guard at all, so any real function
flips every override-less flow out of the no-enforcement branch. Checked before
choosing, since a third remedy would have beaten both offered ones.
Resolution keyed on authorship, the boundary theme 6 already uses:
- run writes the config -> install at both levels (ours is the only flow)
- config is theirs -> per-flow only, in our own flow file; never add a
host-level resolver to a config we did not write
Traced the same boundary through the devtool block, which also lives in that
config: the guest case hands the developer two lines for their own config (flow
registration, which FIX-1159 already prints, and the devtool block) rather than
writing either. Disclosed cost: the DevTool session list will not show our
flow in the guest case.
Theme 6 gained the general form, which is the transferable part: the guarantee
is about BEHAVIOUR, not only files. Every file rule can hold while a
recommended one-line config change breaks their app, so the test is "does
anything the project already had behave differently after this run".
Sweeps: answer-claims, status-claims, and resolver-claims re-run after editing.
The resolver sweep caught a residual of this very edit — the superseded
"install at both levels" paragraph left dangling mid-sentence after its opening
was replaced. Removed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… claim; make the refusal exist on both branches F4 — Q6's derivation was stale on the gate it cited. FIX-1159 at head (6b2c409) narrowed the dev-command row: "Reported for every host; required only where the next-steps block spends it — the mounted-route topology. No usable script on a Next host -> refuse. On a plain-Node host -> report `none` and proceed." The sentence Q6 quoted no longer exists. The conclusion survives on a gate Q6 never named: the package-manager row, "Neither a field nor any lockfile in the whole chain -> `undeclared`, which also refuses", backed by a stated design rule refusing any ambient signal. An empty directory and a bare `npm init -y` both trip it. Both consequences ran against the owner. Option (b) was priced as "requires relaxing the dev-command refusal for the second-process case" — that relaxation is already in FIX-1159, so (b) costs less than stated. Re-priced honestly: on the two gates checked, `npm init -y && npm install` would proceed, so (b) may need only a documented precondition rather than a relaxation — with the caveat stated that I have not walked every refusal. Also withdrew the argument that the skill "owes this anyway" because a script-less project was refused rather than served as a second process: that was fixed in FIX-1159 independently, which removes the argument while making (b) cheaper. The recommendation now stands on the audience alone. F5 — Q5's closing paragraph still said the guarantee is "narrower than greenfield's, which has both layers", two paragraphs after the same section says greenfield takes no credential, and after theme 8 recorded that claim as wrong. Q5 is closed and kept as the copy future readers are sent to, so the hazard was real: derive from it and one of greenfield's controls looks redundant. Corrected to one control each, different rather than lesser. F6 — the credential startup-refusal was defined on the config, which the guest branch does not produce. Applying the standing test: scenario "developer never fills the variable, guest case" returned PASS. Moved to the flow file, which is written on both branches, so the refusal holds regardless of who owns the config. And the standing check enumerated topology only, while the resolver rule branches on authorship — leaving the guest case exercised by nothing. Widened to both axes, with the observation that this is the same defect the theme names one paragraph above, committed against the theme's own check. Repaired the splice at the same site: the guest-case paragraph had been inserted into the middle of the four-item divergence list, producing "and **And in the guest case**" and orphaning the fourth item below a paragraph break. Also withdrew this document's claim that FIX-548's spec is "the accurate record" on Q6, and separated "Q6 does not block that re-approval" (still true) from "the re-approval is safe to take" (no longer true, for reasons of its own). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 316fa7cb8a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| round claimed it did; one control each, chosen because it is the one that works on that path. **Brownfield cannot be fixed the same way** — theme | ||
| 6 forbids rewriting a `dev` script the developer authored, and printing a flag does not reach | ||
| someone who starts their server from memory. **So the brownfield run configures a non-default | ||
| principal resolver on what it generates.** That is the condition |
There was a problem hiding this comment.
Preserve loopback on the second-process path
For the plain-Node second-process branch, this generalization is false: theme 5 explicitly keeps fsdev serve --host 127.0.0.1 at lines 427–431, so that brownfield topology has both the loopback bind and the credential. Because its custom resolver makes assertNetworkBindIsAuthenticated permit the default non-loopback bind, an implementer following this “brownfield has no bind” model could omit the host flag, and §1's second-process proof would still pass because it checks only credential acceptance/refusal. Split this security rule by topology and require the second-process proof to assert that its server remains loopback-bound.
Useful? React with 👍 / 👎.
…ond-process has both P2, and the mirror of a correction already in this document. An early round claimed greenfield had "both layers"; the correction stated "one control each", which is right about greenfield and over-generalises the other way — the plain-Node second-process branch has BOTH the loopback bind (theme 5 keeps `fsdev serve --host 127.0.0.1` in its printed command) and the credential. Verified the mechanism in packages/node/src/bind-guard.ts: the guard returns early when `isLoopbackHost(opts.host)`, otherwise filters flows on `flow.authentication?.resolvePrincipal` and returns on `unauthenticated.length === 0`. The second-process branch installs a per-flow resolver, so with our flow the only registered flow every flow authenticates and a non-loopback bind is PERMITTED. So: implementer reads "brownfield has no bind", drops the flag, guard does not object, and §1's second-process proof still passes because it asserted only credential acceptance and refusal. Check that cannot fail in the motivating scenario. Severity stated honestly in the doc: the credential still refuses unauthenticated callers, so this loses a specified layer rather than opening the endpoint. Folded as a per-(path x topology) matrix rather than "except second-process", with the generalisation that actually holds: the BIND follows who authors the command that starts the server (our scripts, our printed command — not the developer's); the CREDENTIAL follows whether the demo ships a browser client to leak it. Neither question runs along greenfield/brownfield, which is why every attempt to state it per path has been wrong. §1's second-process proof now asserts the server stays loopback-bound, and says why both halves are required: this is the one topology with two controls, and each can be dropped without the other noticing. Q5 corrected in both directions — it had been wrong claiming greenfield had both layers, then wrong again with a flat "one control each" that erased the second-process pair. Granularity sweep per the standing lesson: two more rules are stated per path while their cause is something else — theme 6's exception (c) (cause: we author the project; content enumerates create-next-app's scripts) and the credential rule (cause: no browser client). Both are masked by Q6 being open. Named and left conditional rather than rewritten for an undecided answer, since rewriting ahead of the decision is how the last flattening happened. Adopted the citation rule as policy and applied it to the remaining sibling quote: cite verified behaviour over a sibling's internals, and name the head any sibling quote was read at. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 31d81f1943
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| printed line" that theme 5 exists to catch. **So the guest case hands the developer two lines | ||
| for their own config** — the one that registers the flow, which FIX-1159 already prints, and | ||
| the `devtool` block beside it — rather than writing either. Their diff review is the consent | ||
| surface, exactly as it is for every other write; what changes is that these two are applied by | ||
| them rather than by us. |
There was a problem hiding this comment.
Apply required config edits during the agent run
When the brownfield project already has an fsdev.config.*, this branch only hands the developer the flow-registration and devtool lines instead of applying them. Until that separate manual edit happens, the CLI preferentially loads the existing config, cannot find the generated flow, and has no bearer token for DevTool; a mounted handler backed by that config likewise cannot expose the flow. This makes the advertised one-agent-run path and its standing command checks impossible for a supported authorship branch, so either apply these additive edits as part of the reviewed agent diff or explicitly add the manual edit to the promised steps and proofs.
Useful? React with 👍 / 👎.
| **(c) The stock serving scripts, greenfield only, narrowed to loopback.** *Named for `dev` | ||
| when it was written, which was the defect: we widened the contract for one key and never asked | ||
| what its siblings do. `create-next-app` ships exactly three — `dev`, `build`, `start` — and | ||
| `build` serves nothing, so the exception covers **`dev` and `start`**, both narrowed to | ||
| loopback.* `create-next-app` |
There was a problem hiding this comment.
Let authenticated production starts bind off-host
For a generated app that later configures real authentication and deploys with the stock npm run build && npm start path, this exception still rewrites start with an explicit loopback hostname. Next's local next start --help confirms that --hostname selects the listening address, so the authenticated server remains unreachable off-host even after satisfying theme 8's stated authentication requirement. Make the production bind conditional on authentication/environment, or make removing the loopback override an explicit required deployment step and cover it in the production proof.
Useful? React with 👍 / 👎.
…ot notice its condition clearing The authorship boundary was wider than its hazard. Inheritance belongs to the host-level resolver alone; keying the whole config off-limits meant the handed-back registration line left nothing we author imported at all. Verified: resolveRuntimeSource returns on a located config BEFORE discoverFlows — exclusive, not preferential. serve passes requireConfig:true with no --no-config; --flow-dir is rejected; --no-config runs a different app. So the standing check required "on both authorship branches" had a guest arm that could not be run. Re-keyed on the hazard: registration and an absent devtool block are applied as additive edits (theme 6, same standard as .gitignore/package.json); a present devtool block is handed over; the host-level resolver is still never written. Conflicts with FIX-1159 decision 1 — flagged, not edited. Theme 6 (c): "does not serve off-host UNTIL authentication is configured" was a conditional implemented as a constant. Generalised into theme 8 as the third question under the matrix — can the justifying condition ever clear? §1 gained the mirror assertion: with a resolver configured, production must be reachable off-host. Index/graph sweep: FIX-548's row still read "safe to take now — a mechanical set" three rounds after that was retracted in prose. FIX-1186 is a sub-issue with no index row. FIX-548 is blocks-blocked by FIX-1159, FIX-1160 and FIX-1162 — the last forbidden in bold by Sequencing. Q6's options: two of three begin "ship one".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 11804f1123
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| a manual step. Second, and not a config-edit question at all: **`modelResolver` is a single | ||
| app-level option on `createFlowState`**, so on the guest branch our demo flow generates through | ||
| *their* resolver. Registration makes the flow reachable; it does not make its model resolvable, | ||
| and nothing in this epic currently says the demo's model must be one the host app can already | ||
| serve. That is a live gap, not a closed one. |
There was a problem hiding this comment.
Bind the guest demo to a model its resolver supports
When the brownfield host already has an fsdev.config.* with a custom modelResolver, the generated flow inherits that resolver, but the spec leaves its demo model unconstrained. If the host resolver does not recognize the generated model ID/provider, the mounted route and every advertised CLI check fail before streaming, so the required guest-config proof at lines 61–66 cannot succeed. Make the install skill select or confirm a model supported by the existing resolver—or refuse with remediation—and exercise that case in the standing check.
Useful? React with 👍 / 👎.
…pinned-model pair (1) The credential's startup refusal was right about coverage, wrong about blast radius. That axis is "whose module graph imports our flow file": on the guest branch their config imports it, loadFsdevConfig wraps the throw into a config-load failure, and their whole app dies without .env.local. The check confirmed it by observing the harm — no bystander flow in the fixture. Split: startup refusal on the author branch, request-time refusal in our own resolver on the guest branch. (2) Exception (c)'s `start` half withdrawn. Redundant against theme 8's config refusal, and harmful: "a platform deploy never runs next start" is false of Docker, Render, Railway, Fly, Heroku, App Runner, and -H has no env binding so HOST=0.0.0.0 cannot override it. The container binds loopback and reads as dead. It also falsified a product statement already relayed to the owner; corrected in theme 8. (3) The standing check was keyed to topology x authorship, both brownfield-internal, leaving theme 9's greenfield shipper exempt from its own block. Re-keyed to shipper x host; "greenfield can always run what it just wrote" withdrawn. (4) The devtool block is app-global in the type, not per-flow. Handed over on the guest branch, never applied. (5) Theme 8's production refusal had no stated predicate. Stated once, per-flow, matching the bind guard. Plus: FIX-1159 pins a provider/model and resolver installation is keyed to authorship — each correct alone, the pair puts our hardcoded model through their resolver. ModelResolver has no supports() and no enumeration, and providers load lazily, so it cannot be interrogated: invoke once end to end, refuse with remediation. Generalised to "what else do we pin that the host also decides?"
Correction: the product statement in this description is false, and has been withdrawnFolded at The statement that is wrong, in "A generated app will not serve in production until authentication is configured" and in the engineering calls:
It was false in two ways. It promised a lift that the mechanism could never deliver — the production control was a hardcoded The corrected statement:
This is true because the only production control is now the config refusal, which is adapter-independent and lifts when the condition lifts. Why Other blocks in the description now superseded
One new finding, not previously on this threadFIX-1159 pins a concrete
Generalised to a standing question: what else do we pin that the host also decides? Open candidates — the provider credential's variable name, the store, module format, the Node 22.18 floor, and Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 242ce1206a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **The `devtool` block** — **handed over on the guest branch, never applied**, with its | ||
| consequence stated in the handed-over diff. It looks per-flow in the reasoning and is |
There was a problem hiding this comment.
Apply absent guest DevTool blocks
When a guest config has no existing devtool block, this unconditional “never applied” rule contradicts Q5's absent-versus-present split at lines 1559–1560, which says an absent block is applied. Fresh evidence after the earlier config-edit comments is that the standing check at lines 594–600 now requires fsdev dev to make an authenticated API call; following this bullet leaves the DevTool without the generated bearer token, so that required check and the printed next step fail. Distinguish absent blocks (apply) from existing blocks (hand over).
Useful? React with 👍 / 👎.
| than a thing the reader has to remember. **And that refusal is itself asserted** — with the | ||
| variable unset, **the run must fail on both authorship branches** — because a mitigation nobody | ||
| exercises is the defect it was written to prevent, wearing a fix's clothes. |
There was a problem hiding this comment.
Limit startup refusal to authored configs
With the credential variable unset on the guest-config branch, this still requires the run to fail and describes the check as a startup refusal. Fresh evidence after the earlier authentication-preservation comment is the branch correction immediately below: lines 449–472 show that an import-time throw prevents the developer's entire config and all existing flows from loading, and therefore require lazy request-time refusal for the generated flow instead. Split this assertion so only the author branch fails at startup, while the guest branch proves request refusal and that its bystander flow remains available.
Useful? React with 👍 / 👎.
| It sits with FIX-1159 because the constraint that makes it hard is the brownfield one: | ||
| **a next-steps block must not print a command the project cannot run**, and greenfield can | ||
| always run what it just wrote. That constraint is precisely why rendering has to vary and | ||
| content must not. |
There was a problem hiding this comment.
Remove the restored greenfield check exemption
For the greenfield template, this restores the exact claim withdrawn at lines 626–629: fsdev dev resolves a separate package and its assets at runtime, so authorship of the generated files does not prove the printed command works. A FIX-548 implementer following this local rationale can omit the runtime command check even though the text-conformance check passes, recreating the unchecked greenfield cell identified at lines 606–624; retain the requirement that every shipper runs what it prints.
Useful? React with 👍 / 👎.
… assertion beside them Both premises the last pass flagged as unconfirmable produced real defects. (1) The credential refusal's check still demanded startup failure on BOTH branches, directly above the paragraphs explaining why an import-time throw takes down the guest's whole config. Split: author branch proves startup failure; guest branch proves the run starts, our flow refuses, and a bystander flow of the host's still serves — the only assertion that fails on a regression to the throw. (2) The devtool reversal over-corrected. "Never applied" contradicted Q5's absent/present split and broke this theme's own standing check, which requires fsdev dev to answer an authenticated call. Corrected to absent -> apply, present -> hand over: with no block present there is nothing of theirs to disturb. (3) "greenfield can always run what it just wrote" was withdrawn in theme 5 and left standing verbatim in theme 6's rendering constraint, where a FIX-548 implementer would read it as licence to skip the runtime command check. Swept on the resulting rule — the explanation and the check are different artifacts and only one of them runs — which found a fourth: theme 8's production-refusal predicate was falsifiable nowhere, since greenfield has one flow and all three readings agree there. Asserted on the guest fixture, where an any-flow reading would refuse the host's entire app in production.
Correcting my own correction: the
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 91f1c4f701
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| same fixture, built and started in production mode, must show the production refusal applying to | ||
| *our* flow while the host's own flow still serves.** That is the only place theme 8's refusal | ||
| predicate is falsifiable: greenfield has one flow, so per-flow, any-flow and host-level readings | ||
| all agree there and the check passes under any of them. Here they diverge, and an **any-flow** |
There was a problem hiding this comment.
Exercise the production guard on a default-resolver flow
Fresh evidence after the earlier production-check correction is that this new guest-fixture proof targets the brownfield demo, which the spec requires to have a non-default per-flow credential resolver (lines 413–415). An uncredentialed request to that flow is therefore refused by its resolver in development too, so the check still passes if the production-only default-resolver guard is absent or uses the wrong predicate; this cannot validate the contract in docs/architecture/authentication.md:122-132. Exercise the production guard against a default-resolver flow with an authenticated bystander flow, so removing or broadening the guard makes the test fail.
AGENTS.md reference: AGENTS.md:L13-L15
Useful? React with 👍 / 👎.
…n guard needs a default-resolver flow Codex P1 at 91f1c4f. The guest-fixture production-refusal assertion targets our own demo flow, which that branch requires to carry a per-flow credential resolver — so the refusal observed is that resolver's, not the production guard's, and the check is green with the guard absent or its predicate wrong. Wider than reported: theme 8's predicate makes the guest flow authenticated, so the refusal never reaches it, and the refusal's carrier is the generated config, which the guest branch does not write. Moved to the author branch and stated by what turns it red: our credentialed flow, a default-resolver flow the guard must refuse, an authenticated bystander it must not. Absent guard, any-flow broadening, and host-level narrowing each fail it. Guest fixture keeps its real result under its real name. Left open: whether a host-level-governed flow counts as authenticated here — theme 8's predicate and theme 5's author-branch install disagree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 19c855e507
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **The production refusal's predicate, stated because it is the fourth reader of "is this flow | ||
| authenticated" and was the only one not to say which question it asks.** It is **per-flow**, and | ||
| it is the same predicate `assertNetworkBindIsAuthenticated` applies: a flow whose | ||
| `authentication.resolvePrincipal` is absent, or is the default body-`userId` resolver by brand, | ||
| is unauthenticated. Not "any flow in the app", and not the host-level resolver. |
There was a problem hiding this comment.
Treat the host fallback as real authentication
On the required author branch, theme 5 installs a custom host-level resolver, and the authoritative resolution order makes every flow without an override inherit it. Excluding that fallback here therefore permanently refuses genuinely authenticated later flows in production, contradicting the promise that configuring authentication lets the app serve normally; it also makes the load-bearing fixture at lines 1102–1104 impossible because that fixture requires an override-less flow with no governing host resolver. Fresh evidence beyond the earlier default-flow comment is that the correction moved the fixture onto the author branch whose mandatory fallback prevents that case from existing. Resolve the effective-resolver predicate and its fixture before implementation.
AGENTS.md reference: AGENTS.md:L13-L15
Useful? React with 👍 / 👎.
| *The registration line is the only edit the run applies to a config it did not author. That is | ||
| the boundary, and it is narrow because each candidate had to earn it separately — the `devtool` | ||
| block was inside it for one round and did not survive contact with its own type.* |
There was a problem hiding this comment.
Keep the DevTool edit inside the stated boundary
When the developer-owned config has no devtool block, lines 554–571 require the run to apply one, but this boundary immediately says flow registration is the only applied config edit and that the DevTool block did not survive. Following this latter rule omits the bearer token and makes the mandatory authenticated fsdev dev check fail. Fresh evidence beyond the earlier absent-DevTool comment is that the correction now exists above while this explicit contradictory restatement remains; include absent DevTool blocks in the applied-edit boundary.
Useful? React with 👍 / 👎.
| **Constraint 3 is the one that was missed, and it is live in a supported path rather than a | ||
| corner case.** FIX-1159 explicitly proceeds when the project has its own `fsdev.config.*`: | ||
| *"Not a collision — proceed. Write no config, write everything else, and hand back the one line | ||
| that registers the new flow in theirs."* (FIX-1159 at `6b2c4093d`, the head this was read at — | ||
| see the citation rule at the end of this theme.) So instructing that developer to add a host-level |
There was a problem hiding this comment.
Move child mechanics back to the child specs
This passage illustrates §2 acting as an unsigned implementation spec: it quotes a child spec at a pinned revision and dictates the exact correction, while the surrounding themes continue for hundreds of lines with resolver placement, fixture construction, comparison mechanics, and exact child-spec edits. The canonical epic template limits this artifact to cross-cutting decisions and routes anything touching one issue's approach or test plan to that issue; retain the shared invariants, ownership, and ordering here, and move the issue-local mechanics and defect history to FIX-1159/FIX-1160/FIX-548 or the lessons document.
AGENTS.md reference: AGENTS.md:L217-L221
Useful? React with 👍 / 👎.
…e false, behaviour is now Q7 A POC served a real three-flow app through @flow-state-dev/node and invoked assertNetworkBindIsAuthenticated as fsdev serve does. Four findings, each contradicting this document: enforcement is whole-app not per-flow; the trigger is the bind host, not the environment; serve() never calls the guard, so neither of this epic's entry paths is covered; and a credentialed flow carries zero information about the guard. Consequence: the production promise is withdrawn for the third time and not rewritten. The behaviour is an open owner decision (Q7) with three forks priced — per-flow vs whole-app, bind address vs deployment, library path guarded or not. Swept the premise rather than the wording: exception (c)'s redundancy argument collapsed with the control, theme 5's negative list and §1's greenfield production assertion both named a control rather than a behaviour. Also: devtool boundary contradiction fixed at the site the correction missed; epic no longer dictates FIX-1159's decision-1 correction. Author-branch fixture assertion withdrawn pending measurement of the host-level fallback. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… not impossible executeServeCommand across five configurations on origin/main @ f56c6b2. The guard does refuse a genuinely host-authenticated app (true false positive, proved by negative control), and the mixed case refuses whole-app. But two escapes work: --allow-unauthenticated, and a hand-written serve() entrypoint. Impossibility framing dropped — it was our alarm and the measurement refuted it. What survives is worse: the sanctioned escape is a flag named --allow-unauthenticated, applied to a fully authenticated app, disabling the guard wholesale, so a later unauthenticated flow binds silently. Q7 gains a fourth priced option — the named minimum fix (judge a flow by its effective resolver per pickPrincipalResolver's precedence). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 640bf64010
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - *Yes* means moving the check into `serve()` so every caller gets it. Cost: modest in code, larger | ||
| in blast radius — it changes behaviour for every existing embedder, and anyone binding `0.0.0.0` | ||
| today with a default-resolver flow starts failing on upgrade. | ||
| - **My recommendation: yes, guard `serve()`**, because "the CLI does it" is a rail that only protects |
There was a problem hiding this comment.
Reframe Q7 around an entry path the epic ships
When Q7 is resolved using this recommendation, moving the bind guard into serve() changes hand-written Node embedders but does not protect the vulnerable greenfield Next.js route: the plain-Node path already starts through the guarded fsdev serve CLI, while createNextHandler never traverses serve(). Fresh evidence beyond the earlier production-guard comments is this revision's own POC at lines 1138–1144, which proves that the mounted route bypasses both APIs. Add and price a remedy that actually reaches mounted/serverless handlers before asking the owner to select the security behavior.
AGENTS.md reference: AGENTS.md:L54-L56
Useful? React with 👍 / 👎.
| **So the control is completed where it is adapter-independent: the generated config refuses to | ||
| serve a default-resolver flow outside development.** Same shape as the runtime floor — refuse | ||
| rather than hand someone something that looks like it works — and it holds on every host, | ||
| including the ones we never see. **This is owner-visible and stated plainly: a generated app | ||
| will not serve in production until authentication is configured**, which for a demo scaffold is |
There was a problem hiding this comment.
Remove the withdrawn production-refusal mandate
Fresh evidence after the earlier production-guard comments is the POC recorded later in this same revision: lines 1104–1118 establish that this promise is false and lines 1171–1175 defer the behavior to Q7, yet this binding theme still directs workers to implement a generated-config refusal and repeats it in the control matrix. A child issue can therefore preempt the open owner decision about per-flow versus whole-app and bind versus deployment semantics; mark this behavior pending Q7 everywhere rather than presenting it as completed.
AGENTS.md reference: AGENTS.md:L54-L56
Useful? React with 👍 / 👎.
| spec revision, so FIX-548 needs another pass rather than only different code. **FIX-1159 is also | ||
| affected**, though not blocked: option (b) would hand it a minimal-project brownfield behaviour it | ||
| does not have today. |
There was a problem hiding this comment.
Gate FIX-1159 on the template decision
If the owner chooses Q6 option (b), lines 1860–1869 add a minimal-project brownfield behavior and proof to FIX-1159, so treating that issue as merely “affected, though not blocked” allows it to implement and land before its required scope is known. That conflicts with the declared FIX-1159 → FIX-1160 → FIX-548 merge order and forces FIX-1159 to reopen after Q6; block its implementation or merge on Q6 as well, unless option (b) is reassigned to a later issue.
Useful? React with 👍 / 👎.
…ved its withdrawal P1: Q7 fork 4 asked whether to guard serve(). Plain-Node already enters through the guarded fsdev serve CLI; greenfield Next mounts through createNextHandler and touches neither serve() nor the CLI. The fix protected the protected path and left both exposed paths exposed. Rewritten to where this can be enforced at all, under the measured constraint that a Next handler has no peer address. Three priced options; (A) recommended; it constrains fork (2). P1: theme 8 still mandated the generated-config refusal, and repeated it in the control matrix, after the narrative had deferred it to Q7. Marked pending at all three sites. P2: FIX-1159 gated on Q6 rather than noted as affected — option (b) gives it a new host shape and a proof, and it merges first. Q6 now gates two issues. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
Coordinator rulings folded. Q7(2): keep the bind address, stop describing it as production — a description matched to a mechanism, no product content, and the alternative invents a deployment signal we do not have. Q7(3): do the named minimum fix, filed as FIX-1189, non-blocking; settled on the framing that only sequencing would have changed the recommendation. Standing constraint until FIX-1189 lands: nothing this epic ships may print or document --allow-unauthenticated as the remedy for a correctly-authenticated app. Owner now sees (1)+(4) as one question instead of four forks. Also: Q6's heading still said it blocks FIX-548's implementation a round after its body was corrected to gate FIX-1159 too. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5183a9c02b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **(A) `createNextHandler` refuses a default-resolver flow unless the app explicitly opts in.** No | ||
| peer address needed — the handler judges the flow's *effective* resolver, which it can see. Cost: | ||
| contained, it is our code and one check at handler construction; the greenfield template must then | ||
| either ship a real resolver or carry the opt-in, which is a template change rather than a | ||
| framework one. What a developer experiences: a scaffolded app refuses its demo route until either | ||
| we configured something or they did, on every host including serverless, with no environment |
There was a problem hiding this comment.
Make option A preserve the greenfield first run
When option A is applied to the greenfield browser template, its default-resolver demo is refused during FIX-548's mandatory first run. Neither escape named here satisfies the objective: theme 8 already establishes that the browser cannot safely hold a generated credential, while an unconditional opt-in permits the same unauthenticated route on every deployed host and collapses back to option C; a development-only opt-in is option B, not A. Fresh evidence beyond the earlier Q7-path finding is that the proposed remedy now reaches the correct handler, but its greenfield escapes still defeat either the first-run or security goal, so this recommendation cannot be put to the owner as currently priced.
AGENTS.md reference: AGENTS.md:L54-L56
Useful? React with 👍 / 👎.
| *Also unresolved rather than absent: the guest whose config already declares a `devtool` block | ||
| still ends the run with a manual step (see the `devtool` bullet below).* |
There was a problem hiding this comment.
Handle guest configs with an existing DevTool block
When the guest config already declares devtool, this leaves the run with a manual edit while the app-global DevTool continues sending its existing credential and the generated demo requires a new per-flow bearer token. In that supported branch the printed fsdev dev step cannot invoke the demo, contradicting the one-agent-run promise and the mandatory shipper × host command walk; the guest proof can miss it because it requires an existing config but not an existing devtool block. Refuse this conflict or specify and prove a compatible integration before the run reports success.
Useful? React with 👍 / 👎.
| "until" resolved to *never*. **The corrected statement is in theme 8**, and it is true because | ||
| the only production control is now the one that lifts. |
There was a problem hiding this comment.
Remove the stale claim that a production control exists
This says the corrected product statement is true because “the only production control” now lifts, but this revision explicitly says that control does not exist at lines 829–832 and 875–885, then withdraws the product statement pending Q7 at lines 1112–1122. Fresh evidence beyond the earlier withdrawn-mandate finding is this surviving affirmative claim that production is already covered; a FIX-548 worker following it could assume the hazard is solved or implement the previously withdrawn refusal, preempting the owner's open decision.
AGENTS.md reference: AGENTS.md:L54-L56
Useful? React with 👍 / 👎.
…roved, review closed Q6 closed: ship one starter plus a specified and proved minimal-project brownfield path. FIX-548 and FIX-1159 unblocked; FIX-1159 carries the minimal-project path as work rather than a condition. Consequence recorded: §1's second-process check is now the epic's only Node coverage. Rename approved (option A), recorded as theme 1b and as a blocking merge edge ahead of FIX-1160 and FIX-1159 — it must land before the packaged skills are distributed. Option C's retention sub-decision and Friday expiry are moot, closed by the choice of A rather than by the clock. Q7 open and non-blocking; fork (4) left standing as an unresolved constraint rather than repriced. Final mandate sweep: theme 8 still directed workers to build the generated-config refusal and restated the withdrawn promise as fact. Deleted, with nothing replacing it. #1301 and #1311 closed unmerged at 11:40Z; this doc and its Linear mirror are the durable record. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m


Someone who hears about FSD today cannot use it. The root README tells them to clone our monorepo, run our tests, and read our reference app. There is no scaffold of any kind, so putting FSD into a project they already have means copying files out of our repo by hand — and the coding assistant they would normally lean on has nothing to go on, so it writes FSD-shaped code that does not run.
Why now. Public Launch points people at a front door that is not there.
What this does
Four issues give a stranger two entry paths, and the epic's central call is that they are different kinds of thing. Starting a new project is a command — one shape, no host to detect, nothing to merge. Adding FSD to a repo that already exists is agent work: an install skill that reads the repo in front of it, with the developer reviewing the diff before accepting it. A deterministic brownfield command was tried and abandoned after three review rounds grew it a separate branch for each of a dozen host shapes, with no round at which they stopped. Detection stays deterministic; deterministic mutation is what goes.
Outcome: a working AI feature streaming from a real model inside their own project, new or existing, without cloning our repository — and an assistant beside them that writes FSD code that runs.
It does not promise "one step". Greenfield is one scaffolding command plus the dev command it prints; brownfield is one agent run the developer reviews.
flowchart TD A["FIX-1159 — brownfield knowledge<br/>detection, install skill content, wiring contract"] --> B["FIX-1160 — the pack<br/>plugin, authoring skills, install skill"] B --> C["FIX-548 — create-flow-state<br/>the greenfield command + template"] D["FIX-1162 — npm names<br/>registered; write access outstanding"] -.release gate, not a merge edge.-> C D --> E["FIX-1186 — publishing identity<br/>owner-operated"]What's asked of you
One starter or two — and please answer by letter (§5 Q6)
Plain terms. We ship a starter that creates a new project. Does v1 ship one — a Next.js app ending at a chat page you can type into — or also a second for backend developers, ending at a server with no screen?
Answer by letter, because two of the three options begin "ship one". The old ask recommended "ship one", which under the current framing means (c) — the option I no longer recommend. An answer given from memory selects (c) while sounding like it could mean (b).
The trade-off changed in your favour and against (c). We told you the Node starter's contents were obtainable via
mkdirplus a brownfield run. That substitute never existed — brownfield only modifies a project that already exists, and an empty directory is refused at the package-manager gate. So cutting the Node starter is not a worse path for backend developers. It is no path: they hand-build a Node project first, or take the Next.js template and dragnextandreactinto a backend service.My recommendation: (b) if FIX-1159 will carry it, otherwise (a). (b) serves the audience without a second artifact to keep green.
What would change my mind: if the launch plan points backend developers at a Node starter by name — a landing page, a comparison table, an announcement. A template that exists to be linked to is worth more than the files it writes, and that is a business fact no spec here has.
Cost of being wrong. Ship one without (b): backend developers meet a closed door during the weeks that matter most — recoverable in a later release. Ship two: a starter kept permanently green for an audience (b) would have served at a fraction of the standing cost, and a FIX-548 spec revision rather than only different code, since its no-
--template-flag decision reopens with it.This blocks the implementation of FIX-548 and FIX-1159 — the second added on review, because option (b) gives FIX-1159 a new host shape and a proof of its own, and it merges first, so a reopen would invalidate work already built on it. It does not block FIX-548's spec re-approval, which is separately held for reasons of its own.
The plugin is now the only way anyone reaches brownfield — does install-by-URL still hold? (§5 Q4)
Plain terms. When you chose no public listing, the plugin carried authoring help: a stranger who never found it still got a running app, just with a less useful assistant. After the split it carries the only way to add FSD to a project someone already has. In practice "install-by-URL" means our docs carry the source, so the real question is whether our documentation is a good enough front door for the epic's headline capability during launch week.
My recommendation: hold URL-only, and make the docs carry it properly. A listing is trivially added later; delisting reads as abandonment. What I would add is a requirement rather than a listing — the install source sits on the getting-started page and in the root README, not only in FIX-1160's own docs.
What would change my mind: if the launch is aimed at "add this to your app" rather than "try this out", brownfield is the headline and burying its only channel one click deep is wrong.
Cost of being wrong. Holding: the most valuable capability is reachable only by people who read far enough. Listing: a public entry to keep green in the noisiest period we will have — the cost you already declined once. Blocks nothing.
What should happen when a generated demo app is reachable without authentication? (§5 Q7)
This replaces a promise I made on this PR and have now withdrawn. The description said, until today, that the generated app "refuses to serve its demo flow in production until real authentication is configured." That is the third version of that promise, and like the two before it, it was written by reasoning from our own rules. A POC then ran the real code, and it is false: nothing on this path keys on production, the refusal is whole-app rather than per-flow, and on neither entry path this epic ships is the guard ever invoked. I am not writing a fourth version before you decide the behaviour.
Plain terms. A generated demo app talks to a real model on the developer's provider key. If it is reachable from a network without authentication, anyone who can reach it spends their money and can act as any user. We believed the framework already refused to serve in that state. It only does so when the server is started with our own CLI command — and both of our paths start it another way.
Four questions fell out of the findings. Two are settled as engineering calls and are recorded in §5 Q7; what is left for you is one choice, because the two remaining forks are mechanism apart and a single decision together.
Settled, not asked: the refusal keys on the bind address, and we stop describing it as production — a description being matched to a mechanism, against the alternative of inventing a deployment signal we do not have. And the bind guard learns to see a host-level resolver (filed as FIX-1189), so a developer who configures authentication correctly is no longer refused and then told by our own error text to pass
--allow-unauthenticated, a flag that switches the protection off entirely.The choice: what does a developer meet when their generated demo is unguarded? The only place we enforce anything today is our CLI — and two of our three topologies don't use the CLI for the route that matters: greenfield Next and brownfield Next both mount inside the developer's own server.
There are two answers, not three, and the reason is worth a sentence. I recommended a third — refuse just the demo route unless the app opts in — and it does not survive pricing. The starter's demo page is a browser page, so it cannot hold a secret; the route handler cannot see where a request came from; and every way of exempting the first run either breaks that first run or turns into one of the two options below. The real constraint, which is the honest answer: the starter cannot have both a working first run and a guarded route. Something has to give, and you are choosing which.
My recommendation: refuse once deployed. Its weakness — that "deployed" is a signal we can't always read correctly — used to be a reason to prefer the third option; now that the third option is empty, it is simply the price of the only one that works. And it fails in the direction a demo scaffold should fail. What would change my mind: evidence that first-hour users commonly deploy to private, non-public hosts — then we would be refusing people who were never exposed, and costing more first runs than we protect keys. That is a business fact I don't have.
Cost of being wrong. Toward permissive: a scaffold whose default deployment is an open model endpoint billed to the developer — the exact thing Q5 already refused to ship. Toward strict: developers meet refusals in setups that were never exposed, and route around the control until it is off everywhere. The asymmetry favours strict, because a refusal is visible and a silent exposure is not.
Blocks any unauthenticated-demo refusal work in every issue.
Parts worth reviewing closely
The rest of this is for whoever reviews the epic — the product owner's job ends above.
Epic doc:
spec/_epics/building-with-fsd.md· Linear: FIX-1161 (Public Launch) · Issues: #1310 FIX-1159 · #1311 FIX-1160 · #1312 FIX-548 · #1313 FIX-1162 · Docs-only, never merged.How to review this — altitude, what's in scope, what's deliberately unsettled
This is an epic-spec: the shared objective and cross-cutting decisions for a set of issues. It is not an implementation plan and it is not any one issue's design.
In scope to challenge:
Out of scope — owned by the individual issue specs:
Feedback in the second list is routed to the issue it concerns as an implementer note, not folded in here.
Engineering calls — decided along the way, no product sign-off needed
devonly —startis withdrawn, and it stands on harm alone. Withscripts.starthard-bound to127.0.0.1and-Hcarrying no environment binding, a container binds loopback, the platform health check never connects, and the app reads as dead with nothing to read — false for DockerCMD ["npm","start"], Render, Railway, Fly, Heroku and App Runner. Its closing sentence claimed the withdrawal was safe because "the only production control is now the one that lifts" — asserting a control the measurement had removed, in a document that withdraws the statement pending Q7. Corrected on the premise. The withdrawal never needed a replacement control; what covers production is open. If this is wrong: every containerized deploy of a generated app fails silently.pickPrincipalResolverfalls back to the host resolver for every flow with no override, so a host-level resolver would 401 the working clients of flows we never named. If this is wrong: we break a stranger's app in the act of being invited into it.loadFsdevConfigwraps any throw into a config-load failure — an import-time throw kills every flow they already had. If this is wrong: a hard startup failure of someone else's app, not a 401.resolveRuntimeSourcereturns on a located config beforediscoverFlowsruns. Thedevtoolblock is applied when absent and handed over when present — it is app-global in the type (onewindow.__FSD_DEVTOOL_CONFIG__for every flow), so overwriting an existing one is a real conflict, while writing an absent one displaces no choice. A guest whose config already declares a block is now a conflict the run must refuse (or prove a compatible integration for), not a manual step it leaves behind — their existingbearerTokenis what the DevTool sends to every flow including ours, which requires the credential the run just generated, so the printedfsdev devcannot invoke the demo at all. That breaks the one-agent-run promise and fails the shipper × host walk. And §1's guest fixture must carry a pre-existingdevtoolblock, because without one the failing case cannot be constructed. If this is wrong: either an unreachable brownfield branch, or a developer's DevTool identity silently replaced.fsdev dev, which resolves a separate package at run time. If this is wrong: a printed command that does not run, on the path we author end to end.executeServeCommand: a host-authenticated app with an override-less flow is refused on a network bind — a true false positive, since the same resolver moved per-flow enforces correctly — and the mixed case refuses whole-app, stopping the correctly-configured flow too. Both escapes work (--allow-unauthenticated; a hand-writtenserve()entrypoint), so this is awkward rather than impossible. What is not survivable is the remedy: a flag named--allow-unauthenticated, applied to a fully authenticated app, disabling the guard wholesale — so a flow added later with no authentication binds silently. Known limit atpackages/node/src/bind-guard.ts:14-18. Non-blocking; sequencing handled when FIX-1189 is picked up. Standing constraint until then: nothing this epic ships may print or document--allow-unauthenticatedas the remedy for a correctly-authenticated app.Themes in full — the nine cross-cutting decisions, with their derivations
The themes live in §2 of the epic doc and are not duplicated here — they run to several thousand words of derivation, and the doc is one click away. In brief:
Full text, always current:
spec/_epics/building-with-fsd.md§2, and the same document mirrored on Linear FIX-1161.