Skip to content

Recipe studio

Generated from openspec/specs/recipe-studio/spec.md — edit that file, not this page.

The admin surface for room furnishing recipes: authoring one, seeing which positions in a room its stations actually reach, checking each station against the live catalogue, and dry-running the result against a real traced HDB unit before any of it ships. It exists so a recipe defect is found while the recipe is being written rather than after a branch, a CI run and a deploy.

Requirement: The recipe studio is admin-only

Section titled “Requirement: The recipe studio is admin-only”

The system SHALL restrict the recipe studio to users holding the platform admin role, using the same gate as the other platform-administration surfaces, and SHALL NOT link to it from a non-admin’s navigation.

Scenario: A non-admin cannot reach the studio

Section titled “Scenario: A non-admin cannot reach the studio”
  • WHEN a signed-in user without the platform admin role opens the recipe studio’s address
  • THEN they are redirected away from it and the studio’s contents are never shown

Scenario: An admin reaches it from the admin navigation

Section titled “Scenario: An admin reaches it from the admin navigation”
  • WHEN a platform admin is signed in
  • THEN the studio appears in the admin section of the navigation alongside the other administration screens, and opens on selection

Requirement: Every part of a shipped recipe can be edited in the studio

Section titled “Requirement: Every part of a shipped recipe can be edited in the studio”

The studio SHALL open on the recipes the product ships with, and SHALL let an admin edit every field that affects furnishing: the recipe’s match labels and area bounds; the ordered list of stations; each station’s identifier, role and whether it is required; its anchor category, search query and minimum width; or, for a station whose piece is built, its carpentry preset, its sizing bounds and its share of the wall; its dependents and their relations and counts; and its ordered slot fallback list. Stations SHALL be reorderable, and slots within a station’s fallback list SHALL be reorderable, because both orders decide the outcome.

An admin SHALL be able to create a station of either kind, and to convert a station between buying its piece and building it. Carpentry is the part of a design most often tuned per unit type, so it is the last thing that should require a code change to author.

  • WHEN an admin adds a wall’s left and right positions to a station that listed only the wall’s centre
  • THEN the station’s fallback list shows four positions in the order given, and every later view in the studio — the slot diagram and the dry run — reflects the edited list rather than the shipped one

Scenario: An edit that the recipe schema rejects is refused

Section titled “Scenario: An edit that the recipe schema rejects is refused”
  • WHEN an admin leaves a station with an empty slot list, an empty anchor query, or a duplicate station identifier
  • THEN the studio names the invalid field and declines to treat the draft as a valid recipe, rather than exporting or dry-running something the product could not load

Scenario: A build station is editable, not merely described

Section titled “Scenario: A build station is editable, not merely described”
  • WHEN an admin opens a station whose piece is built
  • THEN its preset, sizing bounds and wall share are editable fields, and the edits carry into the draft, the dry run and the published set

Scenario: A station is converted from bought to built

Section titled “Scenario: A station is converted from bought to built”
  • WHEN an admin turns a catalogue station into a built one
  • THEN the station keeps its identifier, role, required flag and slot list, loses its catalogue query, and gains a build specification — because exactly one source is legal and the studio must not leave the draft holding both

Requirement: Recipe order is visible and its consequences are stated

Section titled “Requirement: Recipe order is visible and its consequences are stated”

Because a room takes the first recipe whose labels and area bounds match it, the studio SHALL present the recipe list in evaluation order, SHALL let an admin change that order, and SHALL warn when a recipe can never be reached because an earlier recipe matches everything it matches.

  • WHEN a recipe’s labels are all also matched by an earlier recipe whose area bounds are no narrower
  • THEN the studio marks the later recipe as unreachable and names the recipe that shadows it

Scenario: Reordering changes which recipe claims a room

Section titled “Scenario: Reordering changes which recipe claims a room”
  • WHEN an admin moves a generic recipe above a specific one that shares a label
  • THEN the studio’s warning updates to reflect the new order

Requirement: A room’s named positions are shown, with the stations that claim them

Section titled “Requirement: A room’s named positions are shown, with the stations that claim them”

The studio SHALL display a room diagram marking every named slot a recipe may use, and SHALL show for each slot which stations list it and at what position in that station’s fallback list. Slots no station claims SHALL be distinguishable from slots that are claimed.

Scenario: A station’s reach is visible without running anything

Section titled “Scenario: A station’s reach is visible without running anything”
  • WHEN an admin selects a station whose slot list names three positions
  • THEN the diagram marks exactly those three positions as that station’s, in fallback order, and the remaining positions are shown as unclaimed by it

Scenario: Two stations competing for a wall are visible

Section titled “Scenario: Two stations competing for a wall are visible”
  • WHEN two stations both list positions on the same wall
  • THEN each of those positions names both stations and the rank it holds in each one’s list

Requirement: A station is checked against the live catalogue while it is written

Section titled “Requirement: A station is checked against the live catalogue while it is written”

The studio SHALL resolve each station’s anchor — and each dependent — against the catalogue as it stands, using the same selection the furnishing path uses, and SHALL report a station that can resolve nothing. It SHALL distinguish a station whose category holds no candidates from one whose candidates all fail its minimum width, because the two call for different fixes.

Scenario: A category with no assets is reported at authoring time

Section titled “Scenario: A category with no assets is reported at authoring time”
  • WHEN a station’s anchor names a category the catalogue holds no ready asset in
  • THEN the studio reports that station as unresolvable and names the empty category, without the admin having to furnish a room to find out

Scenario: A minimum width no asset meets is reported separately

Section titled “Scenario: A minimum width no asset meets is reported separately”
  • WHEN a station’s category holds candidates but every one of them is narrower than the station’s minimum width
  • THEN the studio reports the minimum width as the cause rather than reporting an empty catalogue

Scenario: A resolvable station names what it would pick

Section titled “Scenario: A resolvable station names what it would pick”
  • WHEN a station’s anchor resolves to at least one catalogue asset
  • THEN the studio lists the leading candidates in the order the furnishing path would try them

Requirement: A recipe can be dry-run against a real traced unit

Section titled “Requirement: A recipe can be dry-run against a real traced unit”

The studio SHALL let an admin choose a published base floorplan and one of its rooms, and run the recipe currently being edited against that room’s real geometry without writing anything. The result SHALL name, for each station, either the asset that would be placed and the slot it landed in, the joinery that would be built and its length, or the reason it was skipped, in the same terms furnishing reports to a user.

The result SHALL also draw the room: its outline, and every piece the run produced at the pose the planner chose. A table of station names answers “did it fit”; only a drawing answers “does this look like a kitchen”, which is the question a recipe is tuned against. The drawing SHALL come from the same dry run as the table, so the picture cannot disagree with the report beside it.

Built joinery SHALL be distinguishable from placed furniture in the drawing. A run is fixed to a wall and a sofa is not; drawing them alike invites an admin to read one as being as movable as the other.

Scenario: A dry run places nothing in the document

Section titled “Scenario: A dry run places nothing in the document”
  • WHEN an admin dry-runs a recipe against a base floorplan’s room
  • THEN the base floorplan is unchanged and no project is created or modified
  • WHEN a station is placed during a dry run
  • THEN the result names the slot it landed in, so an admin can see which entry in the fallback list won and which were passed over

Scenario: Built joinery is reported, not only bought furniture

Section titled “Scenario: Built joinery is reported, not only bought furniture”
  • WHEN a dry run includes a station that builds its piece
  • THEN the result lists the run with its preset and its length, rather than omitting it because nothing was bought

Scenario: The result is drawn, not only listed

Section titled “Scenario: The result is drawn, not only listed”
  • WHEN a dry run places or builds anything
  • THEN the room is drawn with each piece at the position and rotation the planner chose

Scenario: A run is drawn differently from a bought piece

Section titled “Scenario: A run is drawn differently from a bought piece”
  • WHEN the drawing contains both joinery and furniture
  • THEN the two are visually distinct, because one is fixed to a wall and the other is not
  • WHEN a station cannot be placed in any of its slots
  • THEN the result gives the reason — nothing in the catalogue matched, no room without blocking a door, no room without blocking the way through, or no room in the positions it tried
  • WHEN an admin edits a station’s slot list and then dry-runs it
  • THEN the run uses the edited recipe, not the recipe the product currently ships

Scenario: Rooms are listed with what the recipe table would make of them

Section titled “Scenario: Rooms are listed with what the recipe table would make of them”
  • WHEN an admin selects a base floorplan
  • THEN its rooms are listed with each room’s floor area and the recipe that would claim it, or that no recipe would

Requirement: An edited recipe is saved as a draft and takes effect only when published

Section titled “Requirement: An edited recipe is saved as a draft and takes effect only when published”

An edited recipe SHALL be saved as a draft and SHALL take effect only when it is published. Publishing SHALL be an explicit act, distinct from saving. Until a draft is published, furnishing SHALL continue to use the recipes currently live, and the studio SHALL say which of the two it is showing.

Scenario: An edit is saved without taking effect

Section titled “Scenario: An edit is saved without taking effect”
  • WHEN an admin edits a recipe
  • THEN the edit is kept as a draft, the studio states that furnishing is still using the live recipes, and nothing a homeowner does is affected until it is published

Scenario: Publishing takes effect without a deploy

Section titled “Scenario: Publishing takes effect without a deploy”
  • WHEN an admin publishes a draft
  • THEN the published set becomes the one furnishing uses, with no code change and no deploy
  • WHEN an admin edits a recipe and reloads the studio
  • THEN the draft is still there, so a half-authored recipe is not lost to a refresh
  • WHEN an admin discards a draft
  • THEN the studio returns to the recipes currently live

Scenario: The built-in recipes can always be recovered

Section titled “Scenario: The built-in recipes can always be recovered”
  • WHEN an admin asks to start again from the recipes the product ships with
  • THEN a draft is created from them, so a bad published set is never a dead end

Requirement: Every published recipe set is a version, and the history is kept

Section titled “Requirement: Every published recipe set is a version, and the history is kept”

The system SHALL record each saved recipe set as its own version rather than overwriting the last, SHALL let an admin annotate a version with what changed in their own words, and SHALL keep the history readable. Because the recipe table decides how every generated room is laid out, an admin SHALL be able to return to any previously published version.

Scenario: Publishing does not destroy what it replaced

Section titled “Scenario: Publishing does not destroy what it replaced”
  • WHEN a set is published over an earlier one
  • THEN the earlier version remains readable, with when it was published and by whom

Scenario: A previous version can be made live again

Section titled “Scenario: A previous version can be made live again”
  • WHEN an admin republishes an earlier version
  • THEN that version becomes the live set, and doing so is itself recorded as a new publication rather than as an erasure of what came between

Requirement: A set whose order makes a recipe unreachable cannot be published

Section titled “Requirement: A set whose order makes a recipe unreachable cannot be published”

Because a room takes the first recipe it matches, a recipe whose every label is already claimed by an earlier recipe with no narrower area bounds can never run. The system SHALL refuse to publish such a set, and SHALL name the unreachable recipe and the one shadowing it. Saving a draft SHALL NOT be refused, so an admin can work through an intermediate state.

Scenario: An unreachable recipe blocks publication

Section titled “Scenario: An unreachable recipe blocks publication”
  • WHEN an admin publishes a set in which an earlier recipe claims every label of a later one
  • THEN publication is refused, and the message names both recipes and the label at fault

Scenario: The same set can still be saved as a draft

Section titled “Scenario: The same set can still be saved as a draft”
  • WHEN an admin saves that set without publishing
  • THEN it is kept, because reordering is an intermediate step on the way to a valid set

Scenario: An area bound that separates two recipes is not shadowing

Section titled “Scenario: An area bound that separates two recipes is not shadowing”
  • WHEN an earlier recipe shares a label with a later one but its area bounds exclude rooms the later one accepts
  • THEN publication is allowed, because rooms outside those bounds still reach the later recipe

Requirement: A stored recipe set that cannot be read is refused, not partly applied

Section titled “Requirement: A stored recipe set that cannot be read is refused, not partly applied”

The system SHALL validate a recipe set against the recipe schema when it is saved, again when it is published, and again when it is read for use. A stored set that no longer satisfies the schema SHALL be refused in favour of the recipes built into the product, and the failure SHALL be visible to an admin rather than silent.

Scenario: A malformed stored set does not break furnishing

Section titled “Scenario: A malformed stored set does not break furnishing”
  • WHEN the live set fails validation on read
  • THEN furnishing proceeds using the built-in recipes rather than failing or partly applying the stored set

Scenario: The fallback is reported, not hidden

Section titled “Scenario: The fallback is reported, not hidden”
  • WHEN the built-in recipes are used because the stored set could not be read
  • THEN the studio says so, because a studio that silently ignores what it was told to publish is worse than one that refuses

Requirement: Authoring is presented as an ordered task with a stated verdict

Section titled “Requirement: Authoring is presented as an ordered task with a stated verdict”

The studio SHALL present authoring as named steps in the order the decisions are made — which rooms the recipe is for, what goes in them, where each piece may go, whether it works, and publishing — and SHALL allow moving between them freely rather than requiring them in sequence. It SHALL show, at all times, either that the recipe is ready or a list of the problems preventing it, in language that names the problem rather than the field.

Scenario: The next thing to do is visible without instruction

Section titled “Scenario: The next thing to do is visible without instruction”
  • WHEN an admin opens a recipe
  • THEN the steps are named and their order is shown, and the step they are on is marked

Scenario: An experienced author is not made to walk the steps

Section titled “Scenario: An experienced author is not made to walk the steps”
  • WHEN an admin selects a later step directly
  • THEN that step opens, without requiring the earlier ones to be completed or revisited

Scenario: Problems are stated, and each is next to its fix

Section titled “Scenario: Problems are stated, and each is next to its fix”
  • WHEN a recipe has a piece that nothing in the catalogue can fill, or a piece that can only be tried in one position
  • THEN the verdict names that piece and what is wrong with it in plain language, and selecting the problem opens the step where it can be corrected

Scenario: A recipe with no problems says so

Section titled “Scenario: A recipe with no problems says so”
  • WHEN every piece resolves and no ordering or schema problem remains
  • THEN the verdict states that the recipe is ready, rather than leaving the absence of warnings to be inferred

Requirement: Positions are chosen by pointing at the plan

Section titled “Requirement: Positions are chosen by pointing at the plan”

Where a piece may go SHALL be set by selecting positions on a diagram of the room, in the order they should be tried, and the diagram SHALL show that order. Selecting a wall SHALL take all of its positions in the order a designer would try them. The studio SHALL NOT require an admin to name a position in order to use it.

  • WHEN an admin selects three positions in turn for a piece
  • THEN those positions are that piece’s fallback list in the order clicked, numbered on the diagram, and the first is what furnishing tries first
  • WHEN an admin deselects a position
  • THEN it leaves that piece’s list and the remaining positions keep their relative order, renumbered
  • WHEN an admin selects a wall rather than a position on it
  • THEN all three of that wall’s positions are added, centre first, because centre is what a designer draws first and the ends are the fallback

Scenario: The consequence of a short list is stated

Section titled “Scenario: The consequence of a short list is stated”
  • WHEN a piece that must fit has only one position
  • THEN the studio says that the piece will fail if that position is taken, rather than leaving it to be discovered by a test run

Requirement: The studio speaks about rooms and furniture, not about the schema

Section titled “Requirement: The studio speaks about rooms and furniture, not about the schema”

The studio SHALL name things as a person who lays out homes would: pieces of furniture rather than stations and anchors, whether a piece must fit rather than whether it is required, a width in metres rather than a millimetre field, and “one on each side” rather than the relation’s name. It SHALL NOT ask for a value that has no effect on the outcome.

Scenario: A piece is described by what it is

Section titled “Scenario: A piece is described by what it is”
  • WHEN a piece is shown in the list
  • THEN it is identified by what it is and what it looks for, not by an internal identifier
  • WHEN a piece resolves to catalogue assets
  • THEN their images are shown, so choosing furniture looks like choosing furniture

Scenario: A field that changes nothing is not asked for

Section titled “Scenario: A field that changes nothing is not asked for”
  • WHEN an admin creates or edits a piece
  • THEN they are not asked for a value that no code reads, and the recipe still round-trips without losing it