Bump version to 0.8.0

Skip the version bump commit if nothing changed, so re-running
script/release for the same version doesn't fail on empty commit.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.storkit/work/1_backlog/430_bug_status_command_traffic_light_dots_not_coloured_in_matrix.md

@@ -0,0 +1,27 @@
+---
+name: "Status command traffic light dots not coloured in Matrix"
+---
+
+# Bug 430: Status command traffic light dots not coloured in Matrix
+
+## Description
+
+The traffic light dots in the status command use plain Unicode characters (○ ● ◑ ✗) which render without colour in Matrix. The HTML formatted_body should use data-mx-color to colour them green/yellow/red.
+
+## How to Reproduce
+
+Send the status command to the bot in Matrix. Observe the dots are monochrome.
+
+## Actual Result
+
+Dots render as plain monochrome Unicode characters.
+
+## Expected Result
+
+Dots render in colour: green (● running), yellow (◑ throttled), red (✗ blocked), grey (○ idle). Use font tag with data-mx-color attribute for Matrix HTML formatted_body.
+
+## Acceptance Criteria
+
+- [ ] HTML formatted_body uses <font data-mx-color="#colour">dot</font> for each traffic light state
+- [ ] Green (#00cc00) for running, yellow (#ffaa00) for throttled, red (#cc0000) for blocked, grey (#888888) for idle
+- [ ] Plain text fallback remains unchanged (Unicode dots for non-HTML transports)

.storkit/work/5_done/426_bug_mergemaster_pipeline_marks_story_done_without_verifying_code_landed_on_master.md

@@ -49,6 +49,26 @@ Story moved to done with no code on master. The merge-queue commit exists on a d
 
 Pipeline should verify that the cherry-pick produced a merge commit on master before advancing to done. If cherry-pick fails or is missing, the story should remain in merge stage with a merge_failure flag.
 
+## Suggested Fix
+
+The code path is: `merge.rs::run_squash_merge` → `pipeline/merge.rs::start_merge_agent_work` → `lifecycle.rs::move_story_to_archived`.
+
+`run_squash_merge` (merge.rs:354) cherry-picks the merge-queue commit onto `project_root` and checks `cp.status.success()`. If it returns `success: true`, `start_merge_agent_work` (pipeline/merge.rs:106) immediately calls `move_story_to_archived`, which moves the story file to `5_done/`. The watcher then commits "storkit: done".
+
+The gap: between the cherry-pick returning success and the story moving to done, nobody verifies the cherry-pick actually produced a code commit on master. Possible failure modes:
+
+1. `project_root` is not on master (e.g. checked out to a merge-queue branch from a concurrent merge)
+2. Cherry-pick exits 0 but produces an empty commit (no code diff)
+3. Cherry-pick succeeds on the wrong branch
+
+**Fix:** After the cherry-pick in `run_squash_merge` succeeds (line 384), before returning `success: true`:
+
+1. Verify `project_root` is on master: `git rev-parse --abbrev-ref HEAD` must equal the base branch
+2. Verify the HEAD commit on master contains the expected merge message (e.g. matches `storkit: merge <story_id>`) or has a non-empty diff
+3. If either check fails, abort the cherry-pick and return `success: false`
+
+This keeps the fix entirely within `run_squash_merge` — no changes needed to the pipeline advance or lifecycle code.
+
 ## Acceptance Criteria
 
 - [ ] Pipeline must not move a story to done unless a merge commit containing the feature code exists on master

.storkit/work/5_done/429_story_interactive_project_setup_wizard_for_new_storkit_projects.md

@@ -0,0 +1,27 @@
+---
+name: "Interactive project setup wizard for new storkit projects"
+agent: coder-opus
+---
+
+# Story 429: Interactive project setup wizard for new storkit projects
+
+## User Story
+
+As a developer adopting storkit on an existing project, I want a guided setup process that scaffolds the .storkit directory and has an agent generate project-specific configuration files, so that I can get up and running without manually writing specs and scripts.
+
+## Acceptance Criteria
+
+- [ ] storkit init scaffolds .storkit/ directory structure, project.toml, and .mcp.json without clobbering any existing files (especially CLAUDE.md)
+- [ ] Setup wizard tracks progress through ordered steps, resumable if interrupted
+- [ ] Step 1: scaffold .storkit/ directory structure and project.toml
+- [ ] Step 2: agent reads codebase and generates specs/00_CONTEXT.md, user confirms or requests revision
+- [ ] Step 3: agent reads tech stack and generates specs/tech/STACK.md, user confirms or requests revision
+- [ ] Step 4: agent creates script/test that runs the project's actual test suite, user runs it to verify, then confirms
+- [ ] Step 5: agent creates script/release tailored to the project's deployment, user confirms
+- [ ] Step 6: agent creates script/test_coverage if the stack supports it, user confirms
+- [ ] Each step gates on user confirmation before advancing to the next
+- [ ] Existing CLAUDE.md is preserved — storkit appends its content or leaves it untouched
+
+## Out of Scope
+
+- TBD

Cargo.lock

@@ -4019,7 +4019,7 @@ checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
 [[package]]
 name = "storkit"
-version = "0.7.0"
+version = "0.8.0"
 dependencies = [
  "async-stream",
  "async-trait",

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "living-spec-standalone",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "living-spec-standalone",
-			"version": "0.7.0",
+			"version": "0.8.0",
 			"dependencies": {
 				"@types/react-syntax-highlighter": "^15.5.13",
 				"react": "^19.1.0",

frontend/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "living-spec-standalone",
 	"private": true,
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"type": "module",
 	"scripts": {
 		"dev": "vite",

frontend/src/api/client.ts

@@ -21,6 +21,19 @@ export type WsRequest =
 			config: ProviderConfig;
 	  };
 
+export interface WizardStepInfo {
+	step: string;
+	label: string;
+	status: string;
+	content?: string;
+}
+
+export interface WizardStateData {
+	steps: WizardStepInfo[];
+	current_step_index: number;
+	completed: boolean;
+}
+
 export interface AgentAssignment {
 	agent_name: string;
 	model: string | null;
@@ -80,6 +93,13 @@ export type WsResponse =
 	| { type: "pong" }
 	/** Sent on connect when the project still needs onboarding (specs are placeholders). */
 	| { type: "onboarding_status"; needs_onboarding: boolean }
+	/** Sent on connect when a setup wizard is active. */
+	| {
+			type: "wizard_state";
+			steps: WizardStepInfo[];
+			current_step_index: number;
+			completed: boolean;
+	  }
 	/** Streaming thinking token from an extended-thinking block, separate from regular text. */
 	| { type: "thinking_token"; content: string }
 	/** Streaming token from a /btw side question response. */
@@ -438,6 +458,7 @@ export class ChatWebSocket {
 	private onAgentConfigChanged?: () => void;
 	private onAgentStateChanged?: () => void;
 	private onOnboardingStatus?: (needsOnboarding: boolean) => void;
+	private onWizardState?: (state: WizardStateData) => void;
 	private onSideQuestionToken?: (content: string) => void;
 	private onSideQuestionDone?: (response: string) => void;
 	private onLogEntry?: (
@@ -528,6 +549,12 @@ export class ChatWebSocket {
 				if (data.type === "agent_state_changed") this.onAgentStateChanged?.();
 				if (data.type === "onboarding_status")
 					this.onOnboardingStatus?.(data.needs_onboarding);
+				if (data.type === "wizard_state")
+					this.onWizardState?.({
+						steps: data.steps,
+						current_step_index: data.current_step_index,
+						completed: data.completed,
+					});
 				if (data.type === "side_question_token")
 					this.onSideQuestionToken?.(data.content);
 				if (data.type === "side_question_done")
@@ -587,6 +614,7 @@ export class ChatWebSocket {
 			onAgentConfigChanged?: () => void;
 			onAgentStateChanged?: () => void;
 			onOnboardingStatus?: (needsOnboarding: boolean) => void;
+			onWizardState?: (state: WizardStateData) => void;
 			onSideQuestionToken?: (content: string) => void;
 			onSideQuestionDone?: (response: string) => void;
 			onLogEntry?: (timestamp: string, level: string, message: string) => void;
@@ -606,6 +634,7 @@ export class ChatWebSocket {
 		this.onAgentConfigChanged = handlers.onAgentConfigChanged;
 		this.onAgentStateChanged = handlers.onAgentStateChanged;
 		this.onOnboardingStatus = handlers.onOnboardingStatus;
+		this.onWizardState = handlers.onWizardState;
 		this.onSideQuestionToken = handlers.onSideQuestionToken;
 		this.onSideQuestionDone = handlers.onSideQuestionDone;
 		this.onLogEntry = handlers.onLogEntry;

frontend/src/components/Chat.tsx

@@ -4,7 +4,11 @@ import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { oneDark } from "react-syntax-highlighter/dist/esm/styles/prism";
 import type { AgentConfigInfo } from "../api/agents";
 import { agentsApi } from "../api/agents";
-import type { AnthropicModelInfo, PipelineState } from "../api/client";
+import type {
+	AnthropicModelInfo,
+	PipelineState,
+	WizardStateData,
+} from "../api/client";
 import { api, ChatWebSocket } from "../api/client";
 import { useChatHistory } from "../hooks/useChatHistory";
 import type { Message, ProviderConfig } from "../types";
@@ -17,6 +21,7 @@ import { LozengeFlyProvider } from "./LozengeFlyContext";
 import { MessageItem } from "./MessageItem";
 import type { LogEntry } from "./ServerLogsPanel";
 import { ServerLogsPanel } from "./ServerLogsPanel";
+import SetupWizard from "./SetupWizard";
 import { SideQuestionOverlay } from "./SideQuestionOverlay";
 import { StagePanel } from "./StagePanel";
 import { WorkItemDetailPanel } from "./WorkItemDetailPanel";
@@ -217,6 +222,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 		new Map(),
 	);
 	const [needsOnboarding, setNeedsOnboarding] = useState(false);
+	const [wizardState, setWizardState] = useState<WizardStateData | null>(null);
 	const onboardingTriggeredRef = useRef(false);
 	const [selectedWorkItemId, setSelectedWorkItemId] = useState<string | null>(
 		null,
@@ -466,6 +472,9 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 			onOnboardingStatus: (onboarding: boolean) => {
 				setNeedsOnboarding(onboarding);
 			},
+			onWizardState: (state: WizardStateData) => {
+				setWizardState(state);
+			},
 			onSideQuestionToken: (content) => {
 				setSideQuestion((prev) =>
 					prev ? { ...prev, response: prev.response + content } : prev,
@@ -978,63 +987,76 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 								gap: "24px",
 							}}
 						>
-							{needsOnboarding && messages.length === 0 && !loading && (
-								<div
-									data-testid="onboarding-welcome"
-									style={{
-										padding: "24px",
-										borderRadius: "12px",
-										background: "#1c2a1c",
-										border: "1px solid #2d4a2d",
-										marginBottom: "8px",
-									}}
-								>
-									<h3
+							{wizardState &&
+								!wizardState.completed &&
+								messages.length === 0 &&
+								!loading && (
+									<SetupWizard
+										wizardState={wizardState}
+										onWizardUpdate={setWizardState}
+										sendMessage={sendMessage}
+									/>
+								)}
+							{needsOnboarding &&
+								!wizardState &&
+								messages.length === 0 &&
+								!loading && (
+									<div
+										data-testid="onboarding-welcome"
 										style={{
-											margin: "0 0 8px 0",
-											color: "#a0d4a0",
-											fontSize: "1.1rem",
+											padding: "24px",
+											borderRadius: "12px",
+											background: "#1c2a1c",
+											border: "1px solid #2d4a2d",
+											marginBottom: "8px",
 										}}
 									>
-										Welcome to Storkit
-									</h3>
-									<p
-										style={{
-											margin: "0 0 16px 0",
-											color: "#ccc",
-											lineHeight: 1.5,
-										}}
-									>
-										This project needs to be set up before you can start writing
-										stories. The agent will guide you through configuring your
-										project goals and tech stack.
-									</p>
-									<button
-										type="button"
-										data-testid="onboarding-start-button"
-										onClick={() => {
-											if (onboardingTriggeredRef.current) return;
-											onboardingTriggeredRef.current = true;
-											setNeedsOnboarding(false);
-											sendMessage(
-												"I just created a new project. Help me set it up.",
-											);
-										}}
-										style={{
-											padding: "10px 20px",
-											borderRadius: "8px",
-											border: "none",
-											backgroundColor: "#a0d4a0",
-											color: "#1a1a1a",
-											cursor: "pointer",
-											fontSize: "0.95rem",
-											fontWeight: 600,
-										}}
-									>
-										Start Project Setup
-									</button>
-								</div>
-							)}
+										<h3
+											style={{
+												margin: "0 0 8px 0",
+												color: "#a0d4a0",
+												fontSize: "1.1rem",
+											}}
+										>
+											Welcome to Storkit
+										</h3>
+										<p
+											style={{
+												margin: "0 0 16px 0",
+												color: "#ccc",
+												lineHeight: 1.5,
+											}}
+										>
+											This project needs to be set up before you can start
+											writing stories. The agent will guide you through
+											configuring your project goals and tech stack.
+										</p>
+										<button
+											type="button"
+											data-testid="onboarding-start-button"
+											onClick={() => {
+												if (onboardingTriggeredRef.current) return;
+												onboardingTriggeredRef.current = true;
+												setNeedsOnboarding(false);
+												sendMessage(
+													"I just created a new project. Help me set it up.",
+												);
+											}}
+											style={{
+												padding: "10px 20px",
+												borderRadius: "8px",
+												border: "none",
+												backgroundColor: "#a0d4a0",
+												color: "#1a1a1a",
+												cursor: "pointer",
+												fontSize: "0.95rem",
+												fontWeight: 600,
+											}}
+										>
+											Start Project Setup
+										</button>
+									</div>
+								)}
 							{messages.map((msg: Message, idx: number) => (
 								<MessageItem
 									key={`msg-${idx}-${msg.role}-${msg.content.substring(0, 20)}`}

frontend/src/components/SetupWizard.tsx

@@ -0,0 +1,354 @@
+import { useCallback, useState } from "react";
+import type { WizardStateData, WizardStepInfo } from "../api/client";
+
+const API_BASE = "/api";
+
+interface SetupWizardProps {
+	wizardState: WizardStateData;
+	onWizardUpdate: (state: WizardStateData) => void;
+	sendMessage: (message: string) => void;
+}
+
+/** Style constants for the wizard UI. */
+const STEP_BG_PENDING = "#1a1f2e";
+const STEP_BG_ACTIVE = "#1c2a1c";
+const STEP_BG_DONE = "#1a2a1a";
+const STEP_BORDER_PENDING = "#2a2f3e";
+const STEP_BORDER_ACTIVE = "#2d4a2d";
+const STEP_BORDER_DONE = "#2d4a2d";
+const COLOR_LABEL = "#ccc";
+const COLOR_LABEL_DONE = "#a0d4a0";
+const COLOR_ACCENT = "#a0d4a0";
+
+function statusIcon(status: string): string {
+	switch (status) {
+		case "confirmed":
+			return "\u2713";
+		case "skipped":
+			return "\u2013";
+		case "generating":
+			return "\u2026";
+		case "awaiting_confirmation":
+			return "?";
+		default:
+			return "\u00B7";
+	}
+}
+
+function stepBackground(status: string, isActive: boolean): string {
+	if (status === "confirmed" || status === "skipped") return STEP_BG_DONE;
+	if (isActive) return STEP_BG_ACTIVE;
+	return STEP_BG_PENDING;
+}
+
+function stepBorder(status: string, isActive: boolean): string {
+	if (status === "confirmed" || status === "skipped") return STEP_BORDER_DONE;
+	if (isActive) return STEP_BORDER_ACTIVE;
+	return STEP_BORDER_PENDING;
+}
+
+/** Messages sent to the chat to trigger agent generation for each step. */
+const STEP_PROMPTS: Record<string, string> = {
+	context:
+		"Read the codebase and generate .storkit/specs/00_CONTEXT.md with a project context spec. Include High-Level Goal, Core Features, Domain Definition, and Glossary sections. Then call the wizard API to store the content: PUT /api/wizard/step/context/content",
+	stack:
+		"Read the tech stack and generate .storkit/specs/tech/STACK.md with a tech stack spec. Include Core Stack, Coding Standards, Quality Gates, and Libraries sections. Then call the wizard API to store the content: PUT /api/wizard/step/stack/content",
+	test_script:
+		"Read the project structure and create script/test — a bash script that runs the project's actual test suite. Then call the wizard API: PUT /api/wizard/step/test_script/content",
+	release_script:
+		"Read the project's deployment setup and create script/release tailored to the project. Then call the wizard API: PUT /api/wizard/step/release_script/content",
+	test_coverage:
+		"If the stack supports coverage reporting, create script/test_coverage. Then call the wizard API: PUT /api/wizard/step/test_coverage/content",
+};
+
+async function apiPost(path: string): Promise<WizardStateData | null> {
+	try {
+		const resp = await fetch(`${API_BASE}${path}`, { method: "POST" });
+		if (!resp.ok) return null;
+		return (await resp.json()) as WizardStateData;
+	} catch {
+		return null;
+	}
+}
+
+function StepCard({
+	step,
+	isActive,
+	onGenerate,
+	onConfirm,
+	onSkip,
+}: {
+	step: WizardStepInfo;
+	isActive: boolean;
+	onGenerate: () => void;
+	onConfirm: () => void;
+	onSkip: () => void;
+}) {
+	const isDone = step.status === "confirmed" || step.status === "skipped";
+
+	return (
+		<div
+			data-testid={`wizard-step-${step.step}`}
+			style={{
+				padding: "16px",
+				borderRadius: "8px",
+				background: stepBackground(step.status, isActive),
+				border: `1px solid ${stepBorder(step.status, isActive)}`,
+				opacity: !isActive && !isDone ? 0.5 : 1,
+				transition: "all 0.2s ease",
+			}}
+		>
+			<div
+				style={{
+					display: "flex",
+					alignItems: "center",
+					gap: "12px",
+				}}
+			>
+				<span
+					style={{
+						width: "24px",
+						height: "24px",
+						borderRadius: "50%",
+						display: "flex",
+						alignItems: "center",
+						justifyContent: "center",
+						fontSize: "14px",
+						fontWeight: 600,
+						background: isDone ? COLOR_ACCENT : "transparent",
+						border: isDone ? "none" : `1px solid ${COLOR_LABEL}`,
+						color: isDone ? "#1a1a1a" : COLOR_LABEL,
+					}}
+				>
+					{statusIcon(step.status)}
+				</span>
+				<span
+					style={{
+						flex: 1,
+						color: isDone ? COLOR_LABEL_DONE : COLOR_LABEL,
+						fontWeight: isActive ? 600 : 400,
+					}}
+				>
+					{step.label}
+				</span>
+				{isActive && step.status === "pending" && (
+					<button
+						type="button"
+						data-testid={`wizard-generate-${step.step}`}
+						onClick={onGenerate}
+						style={{
+							padding: "6px 14px",
+							borderRadius: "6px",
+							border: "none",
+							backgroundColor: COLOR_ACCENT,
+							color: "#1a1a1a",
+							cursor: "pointer",
+							fontSize: "0.85rem",
+							fontWeight: 600,
+						}}
+					>
+						Generate
+					</button>
+				)}
+				{isActive && step.status === "generating" && (
+					<span style={{ color: "#aaa", fontSize: "0.85rem" }}>
+						Generating...
+					</span>
+				)}
+			</div>
+
+			{step.content && step.status === "awaiting_confirmation" && (
+				<div style={{ marginTop: "12px" }}>
+					<pre
+						data-testid={`wizard-preview-${step.step}`}
+						style={{
+							background: "#111",
+							padding: "12px",
+							borderRadius: "6px",
+							fontSize: "0.8rem",
+							color: "#ddd",
+							whiteSpace: "pre-wrap",
+							maxHeight: "200px",
+							overflow: "auto",
+							margin: "0 0 12px 0",
+						}}
+					>
+						{step.content}
+					</pre>
+					<div style={{ display: "flex", gap: "8px" }}>
+						<button
+							type="button"
+							data-testid={`wizard-confirm-${step.step}`}
+							onClick={onConfirm}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "none",
+								backgroundColor: COLOR_ACCENT,
+								color: "#1a1a1a",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+								fontWeight: 600,
+							}}
+						>
+							Confirm
+						</button>
+						<button
+							type="button"
+							data-testid={`wizard-revise-${step.step}`}
+							onClick={onGenerate}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "1px solid #555",
+								backgroundColor: "transparent",
+								color: "#ccc",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+							}}
+						>
+							Revise
+						</button>
+						<button
+							type="button"
+							data-testid={`wizard-skip-${step.step}`}
+							onClick={onSkip}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "1px solid #555",
+								backgroundColor: "transparent",
+								color: "#888",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+							}}
+						>
+							Skip
+						</button>
+					</div>
+				</div>
+			)}
+
+			{isActive && step.status === "pending" && !step.content && (
+				<div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+					<button
+						type="button"
+						data-testid={`wizard-skip-${step.step}`}
+						onClick={onSkip}
+						style={{
+							padding: "4px 10px",
+							borderRadius: "6px",
+							border: "1px solid #444",
+							backgroundColor: "transparent",
+							color: "#888",
+							cursor: "pointer",
+							fontSize: "0.8rem",
+						}}
+					>
+						Skip this step
+					</button>
+				</div>
+			)}
+		</div>
+	);
+}
+
+export default function SetupWizard({
+	wizardState,
+	onWizardUpdate,
+	sendMessage,
+}: SetupWizardProps) {
+	const [, setRefreshKey] = useState(0);
+
+	const handleGenerate = useCallback(
+		(step: WizardStepInfo) => {
+			const prompt = STEP_PROMPTS[step.step];
+			if (prompt) {
+				sendMessage(prompt);
+			}
+		},
+		[sendMessage],
+	);
+
+	const handleConfirm = useCallback(
+		async (step: WizardStepInfo) => {
+			const result = await apiPost(`/wizard/step/${step.step}/confirm`);
+			if (result) {
+				onWizardUpdate(result);
+				setRefreshKey((k) => k + 1);
+			}
+		},
+		[onWizardUpdate],
+	);
+
+	const handleSkip = useCallback(
+		async (step: WizardStepInfo) => {
+			const result = await apiPost(`/wizard/step/${step.step}/skip`);
+			if (result) {
+				onWizardUpdate(result);
+				setRefreshKey((k) => k + 1);
+			}
+		},
+		[onWizardUpdate],
+	);
+
+	if (wizardState.completed) {
+		return (
+			<div
+				data-testid="wizard-complete"
+				style={{
+					padding: "24px",
+					borderRadius: "12px",
+					background: STEP_BG_DONE,
+					border: `1px solid ${STEP_BORDER_DONE}`,
+					textAlign: "center",
+				}}
+			>
+				<h3 style={{ margin: "0 0 8px 0", color: COLOR_ACCENT }}>
+					Setup Complete
+				</h3>
+				<p style={{ margin: 0, color: COLOR_LABEL }}>
+					Your project is configured. You can start writing stories.
+				</p>
+			</div>
+		);
+	}
+
+	return (
+		<div
+			data-testid="setup-wizard"
+			style={{
+				display: "flex",
+				flexDirection: "column",
+				gap: "12px",
+			}}
+		>
+			<div style={{ marginBottom: "8px" }}>
+				<h3
+					style={{
+						margin: "0 0 4px 0",
+						color: COLOR_ACCENT,
+						fontSize: "1.1rem",
+					}}
+				>
+					Project Setup Wizard
+				</h3>
+				<p style={{ margin: 0, color: "#999", fontSize: "0.85rem" }}>
+					Step {wizardState.current_step_index + 1} of{" "}
+					{wizardState.steps.length}
+				</p>
+			</div>
+
+			{wizardState.steps.map((step, idx) => (
+				<StepCard
+					key={step.step}
+					step={step}
+					isActive={idx === wizardState.current_step_index}
+					onGenerate={() => handleGenerate(step)}
+					onConfirm={() => handleConfirm(step)}
+					onSkip={() => handleSkip(step)}
+				/>
+			))}
+		</div>
+	);
+}

script/release

@@ -59,7 +59,11 @@ PACKAGE_LOCK="${SCRIPT_DIR}/frontend/package-lock.json"
 echo "==> Regenerated package-lock.json"
 
 git add "$CARGO_TOML" "$CARGO_LOCK" "$PACKAGE_JSON" "$PACKAGE_LOCK"
-git commit -m "Bump version to ${VERSION}"
+if git diff --cached --quiet; then
+  echo "==> Version already at ${VERSION}, skipping commit"
+else
+  git commit -m "Bump version to ${VERSION}"
+fi
 
 if ! command -v cross >/dev/null 2>&1; then
   echo "Error: 'cross' is not installed. Run: cargo install cross"
@@ -109,10 +113,10 @@ fi
 MERGE_RE="^(storkit|story-kit): merge "
 if [ -n "$LOG_RANGE" ]; then
   MERGED_RAW=$(git log "$LOG_RANGE" --pretty=format:"%s" --no-merges \
-    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u)
+    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u || true)
 else
   MERGED_RAW=$(git log --pretty=format:"%s" --no-merges \
-    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u)
+    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u || true)
 fi
 
 # Categorise merged work items and format names.
@@ -138,13 +142,13 @@ if [ -n "$LOG_RANGE" ]; then
     | grep -Ev "^(storkit|story-kit): " \
     | grep -Ev "^Revert \"(storkit|story-kit): " \
     | grep -v "^Bump version" \
-    | sed 's/^/- /')
+    | sed 's/^/- /' || true)
 else
   MANUAL=$(git log --pretty=format:"%s" --no-merges \
     | grep -Ev "^(storkit|story-kit): " \
     | grep -Ev "^Revert \"(storkit|story-kit): " \
     | grep -v "^Bump version" \
-    | sed 's/^/- /')
+    | sed 's/^/- /' || true)
 fi
 
 # ── Generate summary overview ─────────────────────────────────

server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "storkit"
-version = "0.7.0"
+version = "0.8.0"
 edition = "2024"
 build = "build.rs"
 

server/src/agents/lifecycle.rs

@@ -102,7 +102,7 @@ pub fn feature_branch_has_unmerged_changes(project_root: &Path, story_id: &str)
 /// * If the story is in `4_merge/`, it is moved to `5_done/` and committed.
 /// * If the story is already in `5_done/` or `6_archived/`, this is a no-op (idempotent).
 /// * If the story is not found in `2_current/`, `4_merge/`, `5_done/`, or `6_archived/`, an error is returned.
-pub fn move_story_to_archived(project_root: &Path, story_id: &str) -> Result<(), String> {
+pub fn move_story_to_done(project_root: &Path, story_id: &str) -> Result<(), String> {
     let sk = project_root.join(".storkit").join("work");
     let current_path = sk.join("2_current").join(format!("{story_id}.md"));
     let merge_path = sk.join("4_merge").join(format!("{story_id}.md"));
@@ -584,10 +584,10 @@ mod tests {
         assert!(result.unwrap_err().contains("not found in work/2_current/"));
     }
 
-    // ── move_story_to_archived tests ──────────────────────────────────────────
+    // ── move_story_to_done tests ──────────────────────────────────────────
 
     #[test]
-    fn move_story_to_archived_finds_in_merge_dir() {
+    fn move_story_to_done_finds_in_merge_dir() {
         use std::fs;
         let tmp = tempfile::tempdir().unwrap();
         let root = tmp.path();
@@ -595,16 +595,16 @@ mod tests {
         fs::create_dir_all(&merge_dir).unwrap();
         fs::write(merge_dir.join("22_story_test.md"), "test").unwrap();
 
-        move_story_to_archived(root, "22_story_test").unwrap();
+        move_story_to_done(root, "22_story_test").unwrap();
 
         assert!(!merge_dir.join("22_story_test.md").exists());
         assert!(root.join(".storkit/work/5_done/22_story_test.md").exists());
     }
 
     #[test]
-    fn move_story_to_archived_error_when_not_in_current_or_merge() {
+    fn move_story_to_done_error_when_not_in_current_or_merge() {
         let tmp = tempfile::tempdir().unwrap();
-        let result = move_story_to_archived(tmp.path(), "99_nonexistent");
+        let result = move_story_to_done(tmp.path(), "99_nonexistent");
         assert!(result.unwrap_err().contains("4_merge"));
     }
 

server/src/agents/merge.rs

@@ -383,6 +383,71 @@ pub(crate) fn run_squash_merge(
         });
     }
 
+    // ── Verify code landed on the correct branch ──────────────────
+    // Guard against the cherry-pick silently landing on the wrong branch
+    // (e.g. a merge-queue branch from a concurrent merge).  If the current
+    // branch is not the base branch, or the HEAD commit has no code diff,
+    // treat the merge as failed so the story stays in the merge stage.
+    let current_branch = Command::new("git")
+        .args(["rev-parse", "--abbrev-ref", "HEAD"])
+        .current_dir(project_root)
+        .output()
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default();
+
+    let base_branch = crate::config::ProjectConfig::load(project_root)
+        .ok()
+        .and_then(|c| c.base_branch.clone())
+        .unwrap_or_else(|| "master".to_string());
+
+    if current_branch != base_branch {
+        all_output.push_str(&format!(
+            "=== VERIFICATION FAILED: expected branch '{base_branch}' but HEAD is on \
+             '{current_branch}'. Cherry-pick landed on wrong branch. ===\n"
+        ));
+        cleanup_merge_workspace(project_root, &merge_wt_path, &merge_branch);
+        return Ok(SquashMergeResult {
+            success: false,
+            had_conflicts,
+            conflicts_resolved,
+            conflict_details: Some(format!(
+                "Cherry-pick landed on '{current_branch}' instead of '{base_branch}'"
+            )),
+            output: all_output,
+            gates_passed: true,
+        });
+    }
+
+    // Verify HEAD commit has actual code changes (not an empty cherry-pick).
+    // Exclude .storkit/ so that story-file-only commits don't pass this check.
+    let diff_stat = Command::new("git")
+        .args(["diff", "--stat", "HEAD~1..HEAD", "--", ".", ":(exclude).storkit"])
+        .current_dir(project_root)
+        .output()
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default();
+
+    if diff_stat.is_empty() {
+        all_output.push_str(
+            "=== VERIFICATION FAILED: cherry-pick produced no code changes on master. ===\n",
+        );
+        cleanup_merge_workspace(project_root, &merge_wt_path, &merge_branch);
+        return Ok(SquashMergeResult {
+            success: false,
+            had_conflicts,
+            conflicts_resolved,
+            conflict_details: Some(
+                "Cherry-pick commit contains no code changes (empty diff)".to_string(),
+            ),
+            output: all_output,
+            gates_passed: true,
+        });
+    }
+
+    all_output.push_str(&format!(
+        "=== Verified: cherry-pick landed on '{base_branch}' with code changes ===\n"
+    ));
+
     // ── Clean up ──────────────────────────────────────────────────
     cleanup_merge_workspace(project_root, &merge_wt_path, &merge_branch);
     all_output.push_str("=== Merge-queue cleanup complete ===\n");

server/src/agents/mod.rs

@@ -10,7 +10,7 @@ use crate::config::AgentConfig;
 use serde::{Deserialize, Serialize};
 
 pub use lifecycle::{
-    close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_archived,
+    close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_done,
     move_story_to_merge, move_story_to_qa, move_story_to_stage, reject_story_from_qa,
 };
 pub use pool::AgentPool;

server/src/agents/pool/lifecycle.rs

@@ -1729,7 +1729,7 @@ stage = "coder"
 
     #[tokio::test]
     async fn archiving_story_removes_agent_entries_from_pool() {
-        use crate::agents::lifecycle::move_story_to_archived;
+        use crate::agents::lifecycle::move_story_to_done;
         use std::fs;
 
         let tmp = tempfile::tempdir().unwrap();
@@ -1746,7 +1746,7 @@ stage = "coder"
 
         assert_eq!(pool.list_agents().unwrap().len(), 3);
 
-        move_story_to_archived(root, "60_story_cleanup").unwrap();
+        move_story_to_done(root, "60_story_cleanup").unwrap();
         pool.remove_agents_for_story("60_story_cleanup");
 
         let remaining = pool.list_agents().unwrap();

server/src/agents/pool/pipeline/advance.rs

@@ -308,7 +308,7 @@ impl AgentPool {
                             "[pipeline] Post-merge tests passed for '{story_id}'. Moving to done."
                         );
                         if let Err(e) =
-                            crate::agents::lifecycle::move_story_to_archived(&project_root, story_id)
+                            crate::agents::lifecycle::move_story_to_done(&project_root, story_id)
                         {
                             slog_error!("[pipeline] Failed to move '{story_id}' to done: {e}");
                         }

server/src/agents/pool/pipeline/merge.rs

@@ -104,7 +104,7 @@ impl AgentPool {
         }
 
         let story_archived =
-            crate::agents::lifecycle::move_story_to_archived(project_root, story_id).is_ok();
+            crate::agents::lifecycle::move_story_to_done(project_root, story_id).is_ok();
         if story_archived {
             self.remove_agents_for_story(story_id);
         }

server/src/http/mcp/story_tools.rs

@@ -1,5 +1,5 @@
 use crate::agents::{
-    close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_archived,
+    close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_done,
 };
 use crate::http::context::AppContext;
 use crate::http::workflow::{
@@ -246,7 +246,7 @@ pub(super) fn tool_accept_story(args: &Value, ctx: &AppContext) -> Result<String
         ));
     }
 
-    move_story_to_archived(&project_root, story_id)?;
+    move_story_to_done(&project_root, story_id)?;
     ctx.agents.remove_agents_for_story(story_id);
 
     Ok(format!(
@@ -1331,7 +1331,7 @@ mod tests {
             .output()
             .unwrap();
 
-        // Create story file in current/ so move_story_to_archived would work.
+        // Create story file in current/ so move_story_to_done would work.
         let current_dir = tmp.path().join(".storkit/work/2_current");
         std::fs::create_dir_all(&current_dir).unwrap();
         std::fs::write(

server/src/http/mod.rs

@@ -14,6 +14,7 @@ pub mod settings;
 pub mod workflow;
 
 pub mod project;
+pub mod wizard;
 pub mod ws;
 
 use agents::AgentsApi;
@@ -131,6 +132,7 @@ type ApiTuple = (
     SettingsApi,
     HealthApi,
     BotCommandApi,
+    wizard::WizardApi,
 );
 
 type ApiService = OpenApiService<ApiTuple, ()>;
@@ -147,6 +149,7 @@ pub fn build_openapi_service(ctx: Arc<AppContext>) -> (ApiService, ApiService) {
         SettingsApi { ctx: ctx.clone() },
         HealthApi,
         BotCommandApi { ctx: ctx.clone() },
+        wizard::WizardApi { ctx: ctx.clone() },
     );
 
     let api_service =
@@ -161,7 +164,8 @@ pub fn build_openapi_service(ctx: Arc<AppContext>) -> (ApiService, ApiService) {
         AgentsApi { ctx: ctx.clone() },
         SettingsApi { ctx: ctx.clone() },
         HealthApi,
-        BotCommandApi { ctx },
+        BotCommandApi { ctx: ctx.clone() },
+        wizard::WizardApi { ctx },
     );
 
     let docs_service =

server/src/http/wizard.rs

@@ -0,0 +1,303 @@
+use crate::http::context::{AppContext, OpenApiResult, bad_request, not_found};
+use crate::io::wizard::{StepStatus, WizardState, WizardStep};
+use poem_openapi::{Object, OpenApi, Tags, param::Path, payload::Json};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+#[derive(Tags)]
+enum WizardTags {
+    Wizard,
+}
+
+/// Response for a single wizard step.
+#[derive(Serialize, Object)]
+struct StepResponse {
+    step: String,
+    label: String,
+    status: String,
+    #[oai(skip_serializing_if = "Option::is_none")]
+    content: Option<String>,
+}
+
+/// Full wizard state response.
+#[derive(Serialize, Object)]
+struct WizardResponse {
+    steps: Vec<StepResponse>,
+    current_step_index: usize,
+    completed: bool,
+}
+
+/// Request body for confirming/skipping a step or submitting content.
+#[derive(Deserialize, Object)]
+struct StepActionPayload {
+    /// Optional content to store for the step (e.g., generated spec).
+    #[oai(skip_serializing_if = "Option::is_none")]
+    content: Option<String>,
+}
+
+impl From<&WizardState> for WizardResponse {
+    fn from(state: &WizardState) -> Self {
+        WizardResponse {
+            steps: state
+                .steps
+                .iter()
+                .map(|s| StepResponse {
+                    step: serde_json::to_value(s.step)
+                        .ok()
+                        .and_then(|v| v.as_str().map(String::from))
+                        .unwrap_or_default(),
+                    label: s.step.label().to_string(),
+                    status: serde_json::to_value(&s.status)
+                        .ok()
+                        .and_then(|v| v.as_str().map(String::from))
+                        .unwrap_or_default(),
+                    content: s.content.clone(),
+                })
+                .collect(),
+            current_step_index: state.current_step_index(),
+            completed: state.completed,
+        }
+    }
+}
+
+fn parse_step(step_str: &str) -> Result<WizardStep, poem::Error> {
+    let quoted = format!("\"{step_str}\"");
+    serde_json::from_str::<WizardStep>(&quoted)
+        .map_err(|_| not_found(format!("Unknown wizard step: {step_str}")))
+}
+
+pub struct WizardApi {
+    pub ctx: Arc<AppContext>,
+}
+
+#[OpenApi(tag = "WizardTags::Wizard")]
+impl WizardApi {
+    /// Get the current wizard state.
+    ///
+    /// Returns the full setup wizard progress including all steps and their
+    /// statuses. Returns 404 if no wizard is active.
+    #[oai(path = "/wizard", method = "get")]
+    async fn get_wizard_state(&self) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Set a step's content and mark it as awaiting confirmation.
+    ///
+    /// Used after the agent generates content for a step. The content is
+    /// stored for preview and the step is marked as awaiting user confirmation.
+    #[oai(path = "/wizard/step/:step/content", method = "put")]
+    async fn set_step_content(
+        &self,
+        step: Path<String>,
+        payload: Json<StepActionPayload>,
+    ) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.set_step_status(
+            wizard_step,
+            StepStatus::AwaitingConfirmation,
+            payload.0.content,
+        );
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Confirm a step and advance to the next.
+    ///
+    /// The step must be the current active step. Returns the updated wizard state.
+    #[oai(path = "/wizard/step/:step/confirm", method = "post")]
+    async fn confirm_step(&self, step: Path<String>) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.confirm_step(wizard_step).map_err(bad_request)?;
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Skip a step and advance to the next.
+    ///
+    /// The step must be the current active step.
+    #[oai(path = "/wizard/step/:step/skip", method = "post")]
+    async fn skip_step(&self, step: Path<String>) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.skip_step(wizard_step).map_err(bad_request)?;
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+
+    /// Mark a step as generating (agent is working on it).
+    #[oai(path = "/wizard/step/:step/generating", method = "post")]
+    async fn mark_generating(&self, step: Path<String>) -> OpenApiResult<Json<WizardResponse>> {
+        let root = self.ctx.state.get_project_root().map_err(bad_request)?;
+        let wizard_step = parse_step(&step.0)?;
+        let mut state =
+            WizardState::load(&root).ok_or_else(|| not_found("No wizard active".to_string()))?;
+
+        state.set_step_status(wizard_step, StepStatus::Generating, None);
+        state.save(&root).map_err(bad_request)?;
+
+        Ok(Json(WizardResponse::from(&state)))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::http::context::AppContext;
+    use poem::http::StatusCode;
+    use poem::test::TestClient;
+    use poem_openapi::OpenApiService;
+    use tempfile::TempDir;
+
+    fn setup() -> (TempDir, TestClient<impl poem::Endpoint>) {
+        let dir = TempDir::new().unwrap();
+        let root = dir.path().to_path_buf();
+        std::fs::create_dir_all(root.join(".storkit")).unwrap();
+
+        let ctx = Arc::new(AppContext::new_test(root.clone()));
+        let api = WizardApi { ctx };
+        let service = OpenApiService::new(api, "test", "0.1.0");
+        let client = TestClient::new(service);
+        (dir, client)
+    }
+
+    #[tokio::test]
+    async fn get_wizard_returns_404_when_no_wizard() {
+        let (_dir, client) = setup();
+        let resp = client.get("/wizard").send().await;
+        resp.assert_status(StatusCode::NOT_FOUND);
+    }
+
+    #[tokio::test]
+    async fn get_wizard_returns_state_when_active() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client.get("/wizard").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["current_step_index"], 1);
+        assert!(!body["completed"].as_bool().unwrap());
+        assert_eq!(body["steps"].as_array().unwrap().len(), 6);
+        assert_eq!(body["steps"][0]["status"], "confirmed");
+    }
+
+    #[tokio::test]
+    async fn confirm_step_advances_wizard() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client.post("/wizard/step/context/confirm").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["current_step_index"], 2);
+        assert_eq!(body["steps"][1]["status"], "confirmed");
+    }
+
+    #[tokio::test]
+    async fn confirm_wrong_step_returns_error() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        // Try to confirm step 3 (stack) when current is step 2 (context)
+        let resp = client.post("/wizard/step/stack/confirm").send().await;
+        resp.assert_status(StatusCode::BAD_REQUEST);
+    }
+
+    #[tokio::test]
+    async fn skip_step_advances_wizard() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client.post("/wizard/step/context/skip").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["steps"][1]["status"], "skipped");
+        assert_eq!(body["current_step_index"], 2);
+    }
+
+    #[tokio::test]
+    async fn set_step_content_marks_awaiting_confirmation() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client
+            .put("/wizard/step/context/content")
+            .body_json(&serde_json::json!({
+                "content": "# My Project\n\nA great project."
+            }))
+            .send()
+            .await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["steps"][1]["status"], "awaiting_confirmation");
+        assert_eq!(
+            body["steps"][1]["content"],
+            "# My Project\n\nA great project."
+        );
+    }
+
+    #[tokio::test]
+    async fn mark_generating_updates_step() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client
+            .post("/wizard/step/context/generating")
+            .send()
+            .await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert_eq!(body["steps"][1]["status"], "generating");
+    }
+
+    #[tokio::test]
+    async fn unknown_step_returns_404() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        let resp = client
+            .post("/wizard/step/nonexistent/confirm")
+            .send()
+            .await;
+        resp.assert_status(StatusCode::NOT_FOUND);
+    }
+
+    #[tokio::test]
+    async fn full_wizard_flow_completes() {
+        let (dir, client) = setup();
+        WizardState::init_if_missing(dir.path());
+
+        // Steps 2-6 (scaffold is already confirmed)
+        let steps = ["context", "stack", "test_script", "release_script", "test_coverage"];
+        for step in steps {
+            let resp = client
+                .post(format!("/wizard/step/{step}/confirm"))
+                .send()
+                .await;
+            resp.assert_status_is_ok();
+        }
+
+        // Check final state
+        let resp = client.get("/wizard").send().await;
+        resp.assert_status_is_ok();
+        let body: serde_json::Value = resp.0.into_body().into_json().await.unwrap();
+        assert!(body["completed"].as_bool().unwrap());
+    }
+}

server/src/http/ws.rs

@@ -2,6 +2,7 @@ use crate::http::context::{AppContext, PermissionDecision};
 use crate::http::workflow::{PipelineState, load_pipeline_state};
 use crate::io::onboarding;
 use crate::io::watcher::WatcherEvent;
+use crate::io::wizard;
 use crate::llm::chat;
 use crate::llm::types::Message;
 use crate::log_buffer;
@@ -46,6 +47,16 @@ enum WsRequest {
     },
 }
 
+/// Serialisable summary of a single wizard step for WebSocket broadcast.
+#[derive(Serialize, Clone)]
+pub struct WizardStepInfo {
+    pub step: String,
+    pub label: String,
+    pub status: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
+}
+
 #[derive(Serialize)]
 #[serde(tag = "type", rename_all = "snake_case")]
 /// WebSocket response messages sent by the server.
@@ -125,6 +136,13 @@ enum WsResponse {
     OnboardingStatus {
         needs_onboarding: bool,
     },
+    /// Sent on connect when a setup wizard is active. Contains the full
+    /// wizard state so the frontend can render the step-by-step UI.
+    WizardState {
+        steps: Vec<WizardStepInfo>,
+        current_step_index: usize,
+        completed: bool,
+    },
     /// Streaming token from a `/btw` side question response.
     SideQuestionToken {
         content: String,
@@ -219,6 +237,35 @@ pub async fn ws_handler(ws: WebSocket, ctx: Data<&Arc<AppContext>>) -> impl poem
             });
         }
 
+        // Push wizard state if an active wizard exists.
+        {
+            if let Ok(root) = ctx.state.get_project_root()
+                && let Some(ws) = wizard::WizardState::load(&root)
+            {
+                let steps: Vec<WizardStepInfo> = ws
+                    .steps
+                    .iter()
+                    .map(|s| WizardStepInfo {
+                        step: serde_json::to_value(s.step)
+                            .ok()
+                            .and_then(|v| v.as_str().map(String::from))
+                            .unwrap_or_default(),
+                        label: s.step.label().to_string(),
+                        status: serde_json::to_value(&s.status)
+                            .ok()
+                            .and_then(|v| v.as_str().map(String::from))
+                            .unwrap_or_default(),
+                        content: s.content.clone(),
+                    })
+                    .collect();
+                let _ = tx.send(WsResponse::WizardState {
+                    steps,
+                    current_step_index: ws.current_step_index(),
+                    completed: ws.completed,
+                });
+            }
+        }
+
         // Push recent server log entries so the client has history on connect.
         {
             let entries = log_buffer::global().get_recent_entries(100, None, None);

server/src/io/fs/scaffold.rs

@@ -289,6 +289,7 @@ fn write_story_kit_gitignore(root: &Path) -> Result<(), String> {
         "work/4_merge/",
         "logs/",
         "token_usage.jsonl",
+        "wizard_state.json",
     ];
 
     let gitignore_path = root.join(".storkit").join(".gitignore");

server/src/io/mod.rs

@@ -4,3 +4,4 @@ pub mod search;
 pub mod shell;
 pub mod story_metadata;
 pub mod watcher;
+pub mod wizard;

server/src/io/wizard.rs

@@ -0,0 +1,351 @@
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::path::Path;
+
+/// Ordered wizard steps for project setup.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum WizardStep {
+    /// Step 1: scaffold .storkit/ directory structure and project.toml
+    Scaffold,
+    /// Step 2: generate specs/00_CONTEXT.md
+    Context,
+    /// Step 3: generate specs/tech/STACK.md
+    Stack,
+    /// Step 4: create script/test
+    TestScript,
+    /// Step 5: create script/release
+    ReleaseScript,
+    /// Step 6: create script/test_coverage
+    TestCoverage,
+}
+
+impl WizardStep {
+    /// All steps in order.
+    pub const ALL: &[WizardStep] = &[
+        WizardStep::Scaffold,
+        WizardStep::Context,
+        WizardStep::Stack,
+        WizardStep::TestScript,
+        WizardStep::ReleaseScript,
+        WizardStep::TestCoverage,
+    ];
+
+    /// Human-readable label for this step.
+    pub fn label(&self) -> &'static str {
+        match self {
+            WizardStep::Scaffold => "Scaffold directory structure",
+            WizardStep::Context => "Generate project context (00_CONTEXT.md)",
+            WizardStep::Stack => "Generate tech stack spec (STACK.md)",
+            WizardStep::TestScript => "Create test script (script/test)",
+            WizardStep::ReleaseScript => "Create release script (script/release)",
+            WizardStep::TestCoverage => "Create test coverage script (script/test_coverage)",
+        }
+    }
+
+    /// Zero-based index of this step.
+    pub fn index(&self) -> usize {
+        Self::ALL.iter().position(|s| s == self).unwrap_or(0)
+    }
+}
+
+/// Status of an individual wizard step.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum StepStatus {
+    /// Not yet started.
+    Pending,
+    /// Agent is generating content for this step.
+    Generating,
+    /// Content generated, awaiting user confirmation.
+    AwaitingConfirmation,
+    /// User confirmed this step.
+    Confirmed,
+    /// User skipped this step.
+    Skipped,
+}
+
+/// State of a single wizard step.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepState {
+    pub step: WizardStep,
+    pub status: StepStatus,
+    /// The generated content (if any) for preview.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
+}
+
+/// Persistent wizard state, stored in `.storkit/wizard_state.json`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WizardState {
+    pub steps: Vec<StepState>,
+    /// True when all steps are confirmed or skipped.
+    pub completed: bool,
+}
+
+impl Default for WizardState {
+    fn default() -> Self {
+        Self {
+            steps: WizardStep::ALL
+                .iter()
+                .map(|&step| StepState {
+                    step,
+                    status: StepStatus::Pending,
+                    content: None,
+                })
+                .collect(),
+            completed: false,
+        }
+    }
+}
+
+impl WizardState {
+    /// Path to the wizard state file relative to the project root.
+    fn state_path(project_root: &Path) -> std::path::PathBuf {
+        project_root.join(".storkit").join("wizard_state.json")
+    }
+
+    /// Load wizard state from disk, or return None if it doesn't exist.
+    pub fn load(project_root: &Path) -> Option<Self> {
+        let path = Self::state_path(project_root);
+        let content = fs::read_to_string(&path).ok()?;
+        serde_json::from_str(&content).ok()
+    }
+
+    /// Save wizard state to disk.
+    pub fn save(&self, project_root: &Path) -> Result<(), String> {
+        let path = Self::state_path(project_root);
+        let content =
+            serde_json::to_string_pretty(self).map_err(|e| format!("Serialize error: {e}"))?;
+        fs::write(&path, content).map_err(|e| format!("Failed to write wizard state: {e}"))
+    }
+
+    /// Create wizard state file if it doesn't already exist.
+    /// Step 1 (Scaffold) is automatically confirmed since `storkit init`
+    /// has already run the scaffold.
+    pub fn init_if_missing(project_root: &Path) {
+        if Self::load(project_root).is_some() {
+            return;
+        }
+        let mut state = Self::default();
+        // Scaffold step is done by the time the server starts.
+        state.steps[0].status = StepStatus::Confirmed;
+        let _ = state.save(project_root);
+    }
+
+    /// Get the current step index (0-based).
+    pub fn current_step_index(&self) -> usize {
+        self.steps
+            .iter()
+            .position(|s| !matches!(s.status, StepStatus::Confirmed | StepStatus::Skipped))
+            .unwrap_or(self.steps.len())
+    }
+
+    /// Mark a step's status and update completion state.
+    pub fn set_step_status(
+        &mut self,
+        step: WizardStep,
+        status: StepStatus,
+        content: Option<String>,
+    ) {
+        if let Some(s) = self.steps.iter_mut().find(|s| s.step == step) {
+            s.status = status;
+            if content.is_some() {
+                s.content = content;
+            }
+        }
+        self.completed = self
+            .steps
+            .iter()
+            .all(|s| matches!(s.status, StepStatus::Confirmed | StepStatus::Skipped));
+    }
+
+    /// Confirm a step. Returns error if the step is not the current one
+    /// (enforces sequential progression).
+    pub fn confirm_step(&mut self, step: WizardStep) -> Result<(), String> {
+        let current_idx = self.current_step_index();
+        let target_idx = step.index();
+        if target_idx != current_idx {
+            return Err(format!(
+                "Cannot confirm step {:?}: current step is {}",
+                step, current_idx
+            ));
+        }
+        self.set_step_status(step, StepStatus::Confirmed, None);
+        Ok(())
+    }
+
+    /// Skip a step. Only the current step can be skipped.
+    pub fn skip_step(&mut self, step: WizardStep) -> Result<(), String> {
+        let current_idx = self.current_step_index();
+        let target_idx = step.index();
+        if target_idx != current_idx {
+            return Err(format!(
+                "Cannot skip step {:?}: current step is {}",
+                step, current_idx
+            ));
+        }
+        self.set_step_status(step, StepStatus::Skipped, None);
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn setup_project(dir: &TempDir) -> std::path::PathBuf {
+        let root = dir.path().to_path_buf();
+        let sk = root.join(".storkit");
+        std::fs::create_dir_all(&sk).unwrap();
+        root
+    }
+
+    #[test]
+    fn default_state_has_all_steps_pending() {
+        let state = WizardState::default();
+        assert_eq!(state.steps.len(), 6);
+        for step in &state.steps {
+            assert_eq!(step.status, StepStatus::Pending);
+        }
+        assert!(!state.completed);
+    }
+
+    #[test]
+    fn init_if_missing_creates_state_with_scaffold_confirmed() {
+        let dir = TempDir::new().unwrap();
+        let root = setup_project(&dir);
+
+        WizardState::init_if_missing(&root);
+
+        let state = WizardState::load(&root).unwrap();
+        assert_eq!(state.steps[0].status, StepStatus::Confirmed);
+        assert_eq!(state.steps[0].step, WizardStep::Scaffold);
+        // Rest should be pending
+        for step in &state.steps[1..] {
+            assert_eq!(step.status, StepStatus::Pending);
+        }
+    }
+
+    #[test]
+    fn init_if_missing_does_not_overwrite_existing() {
+        let dir = TempDir::new().unwrap();
+        let root = setup_project(&dir);
+
+        // Create a custom state
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        state.steps[1].status = StepStatus::Confirmed;
+        state.save(&root).unwrap();
+
+        // init_if_missing should not overwrite
+        WizardState::init_if_missing(&root);
+
+        let loaded = WizardState::load(&root).unwrap();
+        assert_eq!(loaded.steps[1].status, StepStatus::Confirmed);
+    }
+
+    #[test]
+    fn save_and_load_round_trip() {
+        let dir = TempDir::new().unwrap();
+        let root = setup_project(&dir);
+
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        state.steps[1].status = StepStatus::AwaitingConfirmation;
+        state.steps[1].content = Some("# My Project\n\nA cool project.".to_string());
+        state.save(&root).unwrap();
+
+        let loaded = WizardState::load(&root).unwrap();
+        assert_eq!(loaded.steps[0].status, StepStatus::Confirmed);
+        assert_eq!(loaded.steps[1].status, StepStatus::AwaitingConfirmation);
+        assert_eq!(
+            loaded.steps[1].content.as_deref(),
+            Some("# My Project\n\nA cool project.")
+        );
+    }
+
+    #[test]
+    fn current_step_index_correct() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+        assert_eq!(state.current_step_index(), 1);
+
+        state.steps[1].status = StepStatus::Skipped;
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn confirm_step_enforces_order() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+
+        // Can confirm the current step (Context, index 1)
+        assert!(state.confirm_step(WizardStep::Context).is_ok());
+
+        // Cannot confirm a step that's not current
+        assert!(state.confirm_step(WizardStep::TestScript).is_err());
+    }
+
+    #[test]
+    fn skip_step_works() {
+        let mut state = WizardState::default();
+        state.steps[0].status = StepStatus::Confirmed;
+
+        assert!(state.skip_step(WizardStep::Context).is_ok());
+        assert_eq!(state.steps[1].status, StepStatus::Skipped);
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn completed_when_all_confirmed_or_skipped() {
+        let mut state = WizardState::default();
+        for step in WizardStep::ALL {
+            state.set_step_status(*step, StepStatus::Confirmed, None);
+        }
+        assert!(state.completed);
+    }
+
+    #[test]
+    fn not_completed_when_some_pending() {
+        let mut state = WizardState::default();
+        state.set_step_status(WizardStep::Scaffold, StepStatus::Confirmed, None);
+        assert!(!state.completed);
+    }
+
+    #[test]
+    fn set_step_status_with_content() {
+        let mut state = WizardState::default();
+        state.set_step_status(
+            WizardStep::Context,
+            StepStatus::AwaitingConfirmation,
+            Some("generated content".to_string()),
+        );
+        assert_eq!(state.steps[1].status, StepStatus::AwaitingConfirmation);
+        assert_eq!(
+            state.steps[1].content.as_deref(),
+            Some("generated content")
+        );
+    }
+
+    #[test]
+    fn load_returns_none_when_no_file() {
+        let dir = TempDir::new().unwrap();
+        assert!(WizardState::load(dir.path()).is_none());
+    }
+
+    #[test]
+    fn step_labels_are_non_empty() {
+        for step in WizardStep::ALL {
+            assert!(!step.label().is_empty());
+        }
+    }
+
+    #[test]
+    fn step_indices_are_sequential() {
+        for (i, step) in WizardStep::ALL.iter().enumerate() {
+            assert_eq!(step.index(), i);
+        }
+    }
+}

server/src/main.rs

@@ -39,6 +39,8 @@ enum CliDirective {
     Help,
     /// `--version` / `-V`
     Version,
+    /// `init [PATH]` — scaffold and start the setup wizard.
+    Init,
     /// An unrecognised flag (starts with `-`).
     UnknownFlag(String),
     /// A positional path argument.
@@ -53,6 +55,7 @@ fn classify_cli_args(args: &[String]) -> CliDirective {
         None => CliDirective::None,
         Some("--help" | "-h") => CliDirective::Help,
         Some("--version" | "-V") => CliDirective::Version,
+        Some("init") => CliDirective::Init,
         Some(a) if a.starts_with('-') => CliDirective::UnknownFlag(a.to_string()),
         Some(_) => CliDirective::Path,
     }
@@ -79,14 +82,22 @@ async fn main() -> Result<(), std::io::Error> {
     let cli_args: Vec<String> = std::env::args().skip(1).collect();
 
     // Handle CLI flags before treating anything as a project path.
+    let is_init = matches!(classify_cli_args(&cli_args), CliDirective::Init);
     match classify_cli_args(&cli_args) {
         CliDirective::Help => {
             println!("storkit [PATH]");
+            println!("storkit init [PATH]");
             println!();
             println!("Serve a storkit project.");
             println!();
             println!("USAGE:");
             println!("  storkit [PATH]");
+            println!("  storkit init [PATH]");
+            println!();
+            println!("COMMANDS:");
+            println!(
+                "  init  Scaffold a new .storkit/ project and start the interactive setup wizard."
+            );
             println!();
             println!("ARGS:");
             println!(
@@ -108,10 +119,15 @@ async fn main() -> Result<(), std::io::Error> {
             eprintln!("Run 'storkit --help' for usage.");
             std::process::exit(1);
         }
-        CliDirective::Path | CliDirective::None => {}
+        CliDirective::Init | CliDirective::Path | CliDirective::None => {}
     }
 
-    let explicit_path = parse_project_path_arg(&cli_args, &cwd);
+    // For `storkit init [PATH]`, the path argument follows "init".
+    let explicit_path = if is_init {
+        parse_project_path_arg(&cli_args[1..], &cwd)
+    } else {
+        parse_project_path_arg(&cli_args, &cwd)
+    };
 
     // When a path is given explicitly on the CLI, it must already exist as a
     // directory.  We do not create directories from the command line.
@@ -126,7 +142,37 @@ async fn main() -> Result<(), std::io::Error> {
         }
     }
 
-    if let Some(explicit_root) = explicit_path {
+    if is_init {
+        // `storkit init [PATH]` — always scaffold, never search parents.
+        let init_root = explicit_path.unwrap_or_else(|| cwd.clone());
+        if !init_root.exists() {
+            std::fs::create_dir_all(&init_root).unwrap_or_else(|e| {
+                eprintln!("error: cannot create directory {}: {e}", init_root.display());
+                std::process::exit(1);
+            });
+        }
+        match io::fs::open_project(
+            init_root.to_string_lossy().to_string(),
+            &app_state,
+            store.as_ref(),
+            port,
+        )
+        .await
+        {
+            Ok(_) => {
+                if let Some(root) = app_state.project_root.lock().unwrap().as_ref() {
+                    config::ProjectConfig::load(root)
+                        .unwrap_or_else(|e| panic!("Invalid project.toml: {e}"));
+                    // Initialize wizard state for the setup flow.
+                    io::wizard::WizardState::init_if_missing(root);
+                }
+            }
+            Err(e) => {
+                eprintln!("error: {e}");
+                std::process::exit(1);
+            }
+        }
+    } else if let Some(explicit_root) = explicit_path {
         // An explicit path was given on the command line.
         // Open it directly — scaffold .storkit/ if it is missing — and
         // exit with a clear error message if the path is invalid.