Skip to content

AI features

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

Tinkerspace’s AI surfaces let a designer work faster inside a project without leaving the 3D editor: rooms are labeled automatically from geometry, a chatbot co-designer edits the scene on request, a moodboard is distilled into a style brief that steers the chatbot, and a walkthrough snapshot can be restyled through an image-to-image pipeline. A broader “generate variants, then round-trip the pick into scene edits” flow is planned but not yet built — only the restyle substrate it would sit on exists today.

Requirement: Room labels persist independently of geometry recomputation

Section titled “Requirement: Room labels persist independently of geometry recomputation”

The system SHALL recompute room polygons on demand from the wall graph and SHALL persist only the user-entered label plus a corner-signature key, so a label survives any wall edit that leaves the room’s corner set unchanged.

Scenario: Label survives an unrelated wall edit

Section titled “Scenario: Label survives an unrelated wall edit”
  • WHEN a user has labeled a room “Living Room” and then edits a wall elsewhere in the floorplan without changing that room’s corners
  • THEN findRooms() recomputes the room’s polygon and the persisted “Living Room” label is still attached to it, keyed by its corner signature

Scenario: Chatbot reasons about rooms by label

Section titled “Scenario: Chatbot reasons about rooms by label”
  • WHEN the chat panel builds sceneContext for a turn
  • THEN it includes each room’s label, centre, and area from floorplan.getRooms(), so the chatbot can resolve a request like “add a desk in the Study” to a room instance

Requirement: Chatbot streams responses and defers tool execution to the client

Section titled “Requirement: Chatbot streams responses and defers tool execution to the client”

The system SHALL stream the assistant’s text response over SSE as it is generated, and SHALL NOT execute any tool call server-side — tool calls are only delivered in the terminal event and are applied by the client against the engine’s mutation API.

Scenario: Text streams before tools are known

Section titled “Scenario: Text streams before tools are known”
  • WHEN POST /chat is processing a turn that ends in a tool call
  • THEN the client receives incremental text SSE events as the model composes its response, followed by a single terminal done event carrying stopReason and the full content (including any tool_use blocks) — no input_json_delta or partial tool payload is ever streamed

Scenario: Tool calls apply through the floorplan mutation API

Section titled “Scenario: Tool calls apply through the floorplan mutation API”
  • WHEN ChatPanel.executeTool() receives a tool_use block from done.content
  • THEN it applies the corresponding change via floorplan.* mutation methods (never a direct Y.Doc write), so the edit is undoable and broadcasts to collaborators through the existing Yjs sync path
  • WHEN a tool_result is posted back to /chat and the model immediately requests another tool call
  • THEN ChatPanel continues auto-firing follow-up turns only up to MAX_AUTO_TURNS (4) before stopping and waiting for user input

Requirement: Chatbot exposes a fixed scene-editing tool set

Section titled “Requirement: Chatbot exposes a fixed scene-editing tool set”

The system SHALL register the same fixed set of seven tools in both the server’s tool list and the client’s tool dispatcher: add_scene_item, update_scene_item, remove_scene_item, search_catalog, add_cladding, update_cladding_material, and furnish_room. The set SHALL be closed: a tool may not be registered on one side only, and changing the set is a spec change.

Scenario: Every registered tool has a client handler

Section titled “Scenario: Every registered tool has a client handler”
  • WHEN the model returns a tool_use block naming one of the seven registered tools
  • THEN ChatPanel.executeTool() has a matching case that executes it against the engine, and it never receives a tool name outside this set

Scenario: A request outside the six tools is not fulfilled as a tool call

Section titled “Scenario: A request outside the six tools is not fulfilled as a tool call”
  • WHEN a user asks the chatbot to add a wall opening or run a batch “make it Scandinavian” material override
  • THEN the chatbot cannot fulfill this as a tool call, because no add_opening or apply_style_preset tool is registered

Scenario: Furnishing the whole unit adds no tool

Section titled “Scenario: Furnishing the whole unit adds no tool”
  • WHEN the user furnishes the whole unit
  • THEN it is carried out without the model, and no eighth tool is registered to serve it; a model asked in chat to furnish the flat instead calls furnish_room once per room

Requirement: Chat requests are metered by a credit charged before the model call

Section titled “Requirement: Chat requests are metered by a credit charged before the model call”

The system SHALL charge one credit from the org’s chat pool before invoking the model, and SHALL refund it if the upstream call fails before completing.

Scenario: Insufficient credits blocks the call

Section titled “Scenario: Insufficient credits blocks the call”
  • WHEN an org’s chat credit pool is empty and a non-admin user sends a chat message
  • THEN POST /chat returns 402 insufficient_credits without calling the model
  • WHEN the credit charge succeeds but the subsequent Anthropic call errors before streaming completes
  • THEN the charged credit is refunded to the same org’s pool

Requirement: Chat and restyle are feature-gated by secret presence

Section titled “Requirement: Chat and restyle are feature-gated by secret presence”

The system SHALL return a 503 with a machine-readable error code when the API key a feature depends on is not configured for the running environment, rather than attempting the call.

Scenario: Chat unavailable without an Anthropic key

Section titled “Scenario: Chat unavailable without an Anthropic key”
  • WHEN ANTHROPIC_API_KEY is not set in the current environment
  • THEN POST /chat returns 503 chat_not_configured

Scenario: Restyle unavailable without a ComfyCloud key

Section titled “Scenario: Restyle unavailable without a ComfyCloud key”
  • WHEN COMFY_API_KEY is not set in the current environment
  • THEN the walkthrough restyle submit route returns 503

Requirement: Walkthrough snapshots can be restyled through ComfyCloud

Section titled “Requirement: Walkthrough snapshots can be restyled through ComfyCloud”

The system SHALL accept a walkthrough viewport snapshot and a style prompt, submit it to ComfyCloud as an image-to-image job scoped to the requesting org, and serve the result once complete.

  • WHEN a designer captures a walkthrough snapshot and submits it with a style prompt via WalkthroughPhotos
  • THEN POST /walkthrough-restyles inserts a restyle_jobs row, mirrors the input image to R2, and submits the job to ComfyCloud; the client polls GET /walkthrough-restyles/:jobId until the job reaches a terminal status
  • WHEN a request to submit or poll a restyle job has no active org context
  • THEN the route rejects it — there is no personal-namespace fallback for restyle jobs

Requirement: Restyle output is never exposed before it is durably stored

Section titled “Requirement: Restyle output is never exposed before it is durably stored”

The system SHALL mirror a completed restyle job’s output bytes to R2 synchronously, before marking the job row as successful, so outputUrl never points at a missing object.

Scenario: R2 write failure prevents a broken success state

Section titled “Scenario: R2 write failure prevents a broken success state”
  • WHEN a restyle job finishes on ComfyCloud but the synchronous mirror-to-R2 write fails
  • THEN the job row is not flipped to a success status, and GET /walkthrough-restyles/:jobId does not yet report an outputUrl
  • WHEN a restyle job’s output has been mirrored to R2 and the row marked successful
  • THEN GET /walkthrough-restyles/:jobId/output.png proxies the org-scoped object with an immutable cache header

Requirement: A generated style profile steers chatbot suggestions

Section titled “Requirement: A generated style profile steers chatbot suggestions”

The system SHALL derive a structured style brief either from a project’s moodboard images via a vision model or from a brief the homeowner states directly, persist it on the project, and fold it into the chatbot’s system prompt as design-style guidance. The profile’s materials and themes SHALL additionally steer which catalog assets recipe-based furnishing selects, so that furnishing performed without the model still reflects the project’s style. palette SHALL NOT influence asset selection: it holds hex colours, which cannot match a catalog entry’s name — colour belongs to a material override, not to choosing which asset to place.

Scenario: Generating a style profile from a moodboard

Section titled “Scenario: Generating a style profile from a moodboard”
  • WHEN a user triggers POST /projects/{id}/style-profile/generate with moodboard images attached to the project
  • THEN the route runs a vision pass over up to 6 of the most recent images and stores a { palette, materials, themes, summary } brief on projects.styleProfile

Scenario: Style profile reaches the chatbot

Section titled “Scenario: Style profile reaches the chatbot”
  • WHEN a project has a generated style profile and the user opens the chat panel
  • THEN ChatPanel fetches the profile best-effort and includes it in sceneContext.styleProfile, which the /chat route renders as a “Design style guidance” section of the system prompt

Scenario: Style profile steers recipe asset selection

Section titled “Scenario: Style profile steers recipe asset selection”
  • WHEN a room is furnished from a recipe on a project that has a style profile, and two catalog assets are equally suitable for the same furniture slot
  • THEN the asset whose name better matches the profile’s materials or themes is the one placed

Scenario: Palette alone changes nothing about which asset is chosen

Section titled “Scenario: Palette alone changes nothing about which asset is chosen”
  • WHEN a room is furnished on a project whose style profile carries a palette but no materials or themes
  • THEN asset selection is identical to the same room furnished with no style profile at all
  • WHEN the asset best matching the style profile does not fit the slot, or its placement would fail validation
  • THEN it is not placed, and selection falls back to an asset that does fit

Scenario: Furnishing without a style profile is unchanged

Section titled “Scenario: Furnishing without a style profile is unchanged”
  • WHEN a room is furnished on a project with no style profile
  • THEN asset selection behaves exactly as it did before this change

Scenario: A style profile is derived from a stated brief, with no images

Section titled “Scenario: A style profile is derived from a stated brief, with no images”
  • WHEN a homeowner answers the onboarding questions and no moodboard images exist on the project
  • THEN a { palette, materials, themes, summary } brief is stored on projects.styleProfile from their answers alone
  • WHEN a style profile is produced from a stated brief rather than from images
  • THEN it carries the same fields as one produced from a moodboard, so everything downstream — the system prompt and recipe asset selection — consumes it without knowing which path produced it

Scenario: A brief with no colours is not a degraded profile

Section titled “Scenario: A brief with no colours is not a degraded profile”
  • WHEN a stated brief yields materials and themes but no palette
  • THEN the profile is stored and used as normal, because palette does not influence asset selection in any case

Scenario: A moodboard generated later replaces the stated brief

Section titled “Scenario: A moodboard generated later replaces the stated brief”
  • WHEN a project whose profile came from a stated brief later has a moodboard profile generated
  • THEN the moodboard-derived profile replaces it, images being the stronger signal

Requirement: Chat-applied scene edits are validated before they are committed

Section titled “Requirement: Chat-applied scene edits are validated before they are committed”

The system SHALL check a chatbot-requested scene-item placement against the same placement rules the editor’s direct-manipulation tools enforce — no overlap with an already-placed item, no collision with a wall, and the whole footprint inside the structural perimeter — before the edit is applied, and SHALL leave the floorplan unchanged when the placement violates any of them.

Scenario: A chat placement that overlaps a placed item is refused

Section titled “Scenario: A chat placement that overlaps a placed item is refused”
  • WHEN the chatbot asks to add a scene item whose footprint overlaps an already-placed item at an overlapping height
  • THEN no scene item is added, the floorplan is unchanged, and the turn produces no undo step

Scenario: A chat placement outside the unit is refused

Section titled “Scenario: A chat placement outside the unit is refused”
  • WHEN the chatbot asks to add a scene item whose footprint falls partly outside the structural perimeter, or intersects a wall
  • THEN no scene item is added and the floorplan is unchanged

Scenario: A chat move is validated against everything except the item being moved

Section titled “Scenario: A chat move is validated against everything except the item being moved”
  • WHEN the chatbot asks to move an already-placed item to a free position
  • THEN the move is applied, and the item’s own current footprint is not counted as an obstacle to itself

Scenario: A valid chat placement still applies

Section titled “Scenario: A valid chat placement still applies”
  • WHEN the chatbot asks to add a scene item at a position that violates none of the rules
  • THEN the item is placed exactly as requested, through the same mutation path as before

Requirement: A refused chat edit is returned to the model as a correctable error

Section titled “Requirement: A refused chat edit is returned to the model as a correctable error”

The system SHALL return a refused placement to the model as a tool error that names which rule was violated, so the model can revise the placement on a following auto-turn rather than reporting success.

Scenario: The refusal names the violated rule

Section titled “Scenario: The refusal names the violated rule”
  • WHEN a placement is refused for overlapping another item
  • THEN the tool result is marked as an error and states that the position overlaps an already-placed item, identifying it

Scenario: The model can retry within the auto-turn budget

Section titled “Scenario: The model can retry within the auto-turn budget”
  • WHEN a placement is refused and auto-turns remain
  • THEN the refusal is posted back to the model as the tool result and the model may issue a corrected placement, subject to the existing auto-turn cap

Scenario: A refusal is visible to the user

Section titled “Scenario: A refusal is visible to the user”
  • WHEN a placement is refused
  • THEN the refusal appears in the chat transcript as a failed outcome, distinguishable at a glance from an edit that changed the scene, and never as a successful edit

Requirement: The chatbot is given each room’s geometry, not just its centroid

Section titled “Requirement: The chatbot is given each room’s geometry, not just its centroid”

The system SHALL include, for every detected room in the scene context, the room’s polygon vertices, the width and depth of its bounding rectangle, the wall segments bounding it, and the openings in those walls with their world positions — so the assistant can reason about where a piece of furniture physically fits rather than inferring from a centre point and an area.

Scenario: A room reaches the model as a shape

Section titled “Scenario: A room reaches the model as a shape”
  • WHEN a chat turn is sent for a floorplan with at least one enclosed room
  • THEN that room’s entry in the scene context carries its polygon vertices and its bounding width and depth, in addition to the label, centre and area it already carried

Scenario: Walls and openings travel with the room they bound

Section titled “Scenario: Walls and openings travel with the room they bound”
  • WHEN a room is enclosed by walls, one of which contains a door
  • THEN the room’s entry lists those wall segments with their endpoints and thickness, and lists the door with its world position, width and height, so the assistant can tell which wall the door is in

Scenario: An unenclosed floorplan degrades quietly

Section titled “Scenario: An unenclosed floorplan degrades quietly”
  • WHEN the wall graph encloses no room (a dangling corner, or a blank canvas)
  • THEN the scene context contains no room geometry and the turn proceeds normally, rather than failing

Scenario: Geometry is derived, never stored

Section titled “Scenario: Geometry is derived, never stored”
  • WHEN room geometry is assembled for a chat turn
  • THEN it is computed on demand from the current wall graph, so it always reflects the floorplan as edited and no polygon is persisted to the document

Requirement: Scene-changing outcomes are reported as structured, actionable results

Section titled “Requirement: Scene-changing outcomes are reported as structured, actionable results”

The system SHALL present the outcome of every scene-changing assistant action as a structured result naming what was changed, what was not, and why — in language addressed to the user — and SHALL offer actions on that result. Raw tool payloads SHALL NOT be the user-facing report of an edit. A piece skipped because an opening was in the way SHALL name that door or window, so the user can tell a layout problem from a catalogue one.

Scenario: A furnished room reports what landed and what did not

Section titled “Scenario: A furnished room reports what landed and what did not”
  • WHEN a room is furnished and some of its planned furniture could not be placed
  • THEN the result names the room, lists what was placed, and states the reason each remaining piece was skipped in plain language rather than as a rule identifier or payload

Scenario: A piece skipped for a door says so

Section titled “Scenario: A piece skipped for a door says so”
  • WHEN every candidate position for a piece would block a door’s swing or approach
  • THEN the reason names that door rather than reporting a generic lack of room, because “there was no room” and “the door would not open” call for different fixes from the user
  • WHEN a scene-changing result is shown
  • THEN the user can move the camera to what changed, switch to editing it directly, undo that result on its own, and request the action again — without typing a follow-up message

Scenario: Requesting the action again produces a different arrangement

Section titled “Scenario: Requesting the action again produces a different arrangement”
  • WHEN the user asks for a furnished room to be done again
  • THEN the room is furnished with a different selection of assets, not the identical one — the recipe path is deterministic, so re-running it unchanged would place exactly what is already there and read as the action having failed

Scenario: Switching to editing hands over the tools, not just the view

Section titled “Scenario: Switching to editing hands over the tools, not just the view”
  • WHEN the user chooses to adjust the room a result describes
  • THEN the room is brought into view and the editor presents the full toolset, so the user is looking at the room with the means to change it rather than only at it

Scenario: Switching to editing lands in the view a room is arranged from

Section titled “Scenario: Switching to editing lands in the view a room is arranged from”
  • WHEN the user chooses to adjust the room a result describes
  • THEN the editor is in the flat top-down plan view, whichever view it was in before — furniture is arranged in plan, and handing over the tools while leaving the camera at an orbiting angle through walls hands over the means without the vantage

Scenario: Raw tool payloads are not the report

Section titled “Scenario: Raw tool payloads are not the report”
  • WHEN the assistant invokes a scene-changing tool
  • THEN the serialized tool input and the raw tool result string are not what the user is shown as the outcome

Scenario: A failed outcome is visually distinct from a successful one

Section titled “Scenario: A failed outcome is visually distinct from a successful one”
  • WHEN an action is refused or places nothing
  • THEN its result is presented as a failure, distinguishable at a glance from a result that changed the scene, and states why

Requirement: The whole unit can be furnished in one action without a model call

Section titled “Requirement: The whole unit can be furnished in one action without a model call”

The system SHALL offer a single action that furnishes every room in the floorplan matching a furnishing recipe. This action SHALL NOT call the language model, SHALL NOT consume chat credits, and SHALL apply the same placement validation as furnishing one room at a time.

Scenario: Every recipe-matched room is furnished

Section titled “Scenario: Every recipe-matched room is furnished”
  • WHEN the user invokes the whole-unit action on a floorplan whose rooms match recipes
  • THEN each matching room is furnished, and each room’s outcome is reported as its own result
  • WHEN the whole-unit action runs
  • THEN no request is made to the chat endpoint and no chat credit is consumed, regardless of the user’s credit balance

Scenario: Prebuilt rooms are reported, not silently omitted

Section titled “Scenario: Prebuilt rooms are reported, not silently omitted”
  • WHEN the floorplan contains rooms that a BTO unit arrives fitted with — kitchen, bathrooms, household shelter — for which no recipe places anything
  • THEN the outcome states that those rooms were left alone because they come fitted, rather than omitting them from the report

Scenario: Validation is not relaxed for the bulk path

Section titled “Scenario: Validation is not relaxed for the bulk path”
  • WHEN the whole-unit action places furniture
  • THEN every placement is validated against walls, door swings and already-placed items on the same terms as a single-room furnishing, and anything failing validation is skipped and reported

Scenario: A floorplan with no matching rooms

Section titled “Scenario: A floorplan with no matching rooms”
  • WHEN the whole-unit action runs against a floorplan where no room matches a recipe
  • THEN nothing is placed and the outcome says so, rather than reporting a successful generation

Requirement: One generation is one undo step

Section titled “Requirement: One generation is one undo step”

The system SHALL make a single furnishing action undoable in one step, whether it furnished one room or the whole unit, and whether it placed furniture, built joinery, or both.

Scenario: A whole-unit generation is undone once

Section titled “Scenario: A whole-unit generation is undone once”
  • WHEN the user undoes immediately after a whole-unit generation that furnished four rooms
  • THEN every item that generation placed is removed by that single undo

Scenario: Undo does not reach past the generation

Section titled “Scenario: Undo does not reach past the generation”
  • WHEN the user undoes a generation applied to a floorplan that already contained furniture
  • THEN only the items that generation placed are removed, and pre-existing items are untouched

Scenario: Built joinery undoes with the furniture that came with it

Section titled “Scenario: Built joinery undoes with the furniture that came with it”
  • WHEN the user undoes a generation that both placed furniture and built a cabinet run
  • THEN the furniture and the cabinet run are both removed by that single undo, leaving no orphaned carpentry behind

Requirement: Suggested next actions are derived from the current scene

Section titled “Requirement: Suggested next actions are derived from the current scene”

The system SHALL offer the user suggested actions computed from the state of the floorplan, so that a suggestion is never offered for work already done.

Scenario: An empty room is offered furnishing

Section titled “Scenario: An empty room is offered furnishing”
  • WHEN the floorplan contains a room matching a recipe that holds no furniture
  • THEN a suggestion to furnish that room is offered, naming the room

Scenario: Suggestions change once the scene changes

Section titled “Scenario: Suggestions change once the scene changes”
  • WHEN a room that was suggested for furnishing has been furnished
  • THEN that suggestion is no longer offered, and suggestions appropriate to a furnished room are offered instead

Requirement: Furnishing uses the published recipe set, with the built-in recipes as the fallback

Section titled “Requirement: Furnishing uses the published recipe set, with the built-in recipes as the fallback”

The system SHALL resolve a room to a recipe using the recipe set most recently published by an administrator. When no set has been published, or the published set cannot be read, it SHALL use the recipes built into the product. Furnishing SHALL NOT depend on that lookup having succeeded: a failure to reach it SHALL degrade to the built-in recipes rather than leaving rooms unfurnished.

Scenario: A published set changes how a room is furnished

Section titled “Scenario: A published set changes how a room is furnished”
  • WHEN an administrator publishes a recipe set that differs from the built-in one, and a room is then furnished
  • THEN the room is laid out by the published recipe, with no deploy in between

Scenario: Nothing published means the built-in recipes

Section titled “Scenario: Nothing published means the built-in recipes”
  • WHEN no recipe set has ever been published and a room is furnished
  • THEN the room is laid out by the recipes built into the product, exactly as before

Scenario: An unreachable recipe service does not stop furnishing

Section titled “Scenario: An unreachable recipe service does not stop furnishing”
  • WHEN the published set cannot be fetched and the user furnishes a room
  • THEN the room is furnished from the built-in recipes rather than reporting a failure

Scenario: Every furnishing path reads the same set

Section titled “Scenario: Every furnishing path reads the same set”
  • WHEN a room is furnished by the assistant, by the whole-unit action, or offered as a suggestion because it is empty
  • THEN all three consult the same published set, so what is offered and what is placed cannot disagree

Requirement: Kitchen cabinetry is built to fit, not resolved from the catalogue

Section titled “Requirement: Kitchen cabinetry is built to fit, not resolved from the catalogue”

Furnishing SHALL generate cabinetry as built-in joinery sized to the room, rather than selecting a catalogue product. A station that builds its piece SHALL NOT consult the catalogue at all, so no product — however it ranks — can be placed as cabinetry.

The generated run SHALL be sized to the wall it sits against, between the run’s minimum and maximum lengths, in whole bays. Where the build declares a share of the wall, the run SHALL take that share of the clear wall it is given, still bounded by those lengths.

Built-in joinery SHALL be generated when the home is furnished, not only when it is asked for by name. A kitchen with appliances standing against bare walls is not a furnished kitchen, and a homeowner cannot ask for something they were never shown. A station marked as replacing something the flat may already have SHALL be understood as a candidate for removal by the designer, not as a reason to withhold it.

Scenario: Furnishing the whole home builds the kitchen’s cabinetry

Section titled “Scenario: Furnishing the whole home builds the kitchen’s cabinetry”
  • WHEN the user furnishes the whole flat
  • THEN the kitchen’s cabinetry is built along with its appliances, rather than being held back until a separate action asks for it by name

Scenario: The cabinetry action places a run on a furnished kitchen

Section titled “Scenario: The cabinetry action places a run on a furnished kitchen”
  • WHEN the user invokes “Add kitchen cabinetry” on a kitchen that already holds its appliances
  • THEN a base cabinet run with a worktop is built against a wall of that kitchen, sized to the wall’s clear length

Scenario: A gadget can never be placed as cabinetry

Section titled “Scenario: A gadget can never be placed as cabinetry”
  • WHEN the catalogue’s best word-overlap match for the cabinetry station is a bench grinder, a stand mixer or any other appliance
  • THEN none of them is placed, because the cabinetry station does not read the catalogue

Scenario: The run fits the room rather than a stock size

Section titled “Scenario: The run fits the room rather than a stock size”
  • WHEN the same cabinetry action runs in a kitchen with a 2.1 m clear wall and again in one with a 3.4 m clear wall
  • THEN each kitchen gets a run sized to its own wall, not the same fixed-width unit in both

Scenario: A predesign holds its proportion across unit types

Section titled “Scenario: A predesign holds its proportion across unit types”
  • WHEN a build declaring a share of the wall is run in a room with a short wall and again in one with a long wall
  • THEN each run takes that share of its own wall, so the design reads the same in both rather than filling one room and looking like a stub in the other

Scenario: Wall units accompany the base run

Section titled “Scenario: Wall units accompany the base run”
  • WHEN a base run is built and the wall above it is clear
  • THEN a wall-unit run is built above it, aligned to the base run

Requirement: A cabinetry run that cannot be built says what it wanted

Section titled “Requirement: A cabinetry run that cannot be built says what it wanted”

When furnishing cannot build a run, the reported reason SHALL name what the run needed — the clear wall length required and the longest run actually available — and SHALL NOT name a rejected catalogue product.

  • WHEN every candidate wall in the kitchen has less clear run than the minimum a cabinet run needs
  • THEN the station is reported as skipped with a reason naming the length needed and the longest clear run found

Scenario: The reason never cites a product

Section titled “Scenario: The reason never cites a product”
  • WHEN a cabinetry run cannot be built for any reason
  • THEN the reason does not mention a catalogue asset name, because no catalogue asset was ever a candidate

Requirement: Built joinery is reported distinctly from placed furniture

Section titled “Requirement: Built joinery is reported distinctly from placed furniture”

A furnishing outcome SHALL report what it built separately from what it placed, naming the built unit and its size, so a user can tell generated joinery from a catalogue product.

Each built run SHALL also report how much of the wall it took — the length built against the clear length available — and a room’s outcome SHALL report its carpentry as a running-metre total, summed for the unit. Running metres are how carpentry is priced, and the proportion is how a design is judged; both are known at the moment the run is planned, so both SHALL be carried on the outcome rather than re-derived later from what happens to be in the document.

Scenario: The result card names the built run

Section titled “Scenario: The result card names the built run”
  • WHEN a cabinetry action builds a base run and a wall run
  • THEN the outcome lists them as built units with their labels and lengths, rather than attributing them to a catalogue asset id

Scenario: A built run reports its share of the wall

Section titled “Scenario: A built run reports its share of the wall”
  • WHEN a run is built against a wall with more clear length than the run took
  • THEN the outcome carries both lengths, so a designer can see the run covers part of the wall rather than only that it exists

Scenario: A furnished home reports its carpentry scope

Section titled “Scenario: A furnished home reports its carpentry scope”
  • WHEN the whole flat is furnished and joinery is built in more than one room
  • THEN the outcome reports the running metres built per room and for the unit as a whole

Scenario: Nothing built and nothing placed is still reported

Section titled “Scenario: Nothing built and nothing placed is still reported”
  • WHEN a room’s furnishing neither places furniture nor builds joinery
  • THEN the outcome reports that nothing happened along with each station’s reason, rather than reporting a success

Requirement: Generated joinery may span more than one wall

Section titled “Requirement: Generated joinery may span more than one wall”

Where a build declares a multi-wall shape, furnishing SHALL plan one run per wall the shape names, each sized to that wall’s own clear span, and SHALL report each run against the wall it stands on. Reporting every leg at the position of the first would be a false statement about the room.

No two runs SHALL occupy the same corner. Two legs meeting at a corner both want the same cube of space, and exactly one may have it — so a later leg is planned against the legs already standing and stops where the first begins. A run that must give up the corner SHALL be shortened rather than refused: a shorter leg is a kitchen, and no leg is not.

Generated joinery SHALL be visible to whatever is planned after it, so that nothing is placed inside a run that already exists.

Scenario: An L is two runs on adjoining walls

Section titled “Scenario: An L is two runs on adjoining walls”
  • WHEN a station whose build declares an L shape is furnished into a room with two usable adjoining walls
  • THEN two runs are built, one on each wall, and each is reported against its own wall

Scenario: The legs do not share the corner

Section titled “Scenario: The legs do not share the corner”
  • WHEN two legs of a shape meet at a corner
  • THEN their footprints do not overlap, and the later leg is shortened rather than refused
  • WHEN a multi-wall build also declares wall units
  • THEN each leg gets its own run above it, aligned to that leg

Scenario: A shape takes what the room actually has

Section titled “Scenario: A shape takes what the room actually has”
  • WHEN a shape names a wall the room does not have, or one that cannot take a run
  • THEN the legs that can be built are built, rather than the whole station failing because one wall was unusable

Scenario: Nothing is placed inside a run that was built

Section titled “Scenario: Nothing is placed inside a run that was built”
  • WHEN a station is planned after one that built joinery
  • THEN the run is among the things it must not overlap, exactly as a placed piece of furniture is

Requirement: A proposed room carries the joinery it would build

Section titled “Requirement: A proposed room carries the joinery it would build”

A proposal describing a room’s arrangement SHALL carry the joinery it would build with the poses that were computed to decide it, alongside the furniture it would place. A proposal that omits its runs can only be drawn as the movable half of the room, which misrepresents a kitchen — the cabinetry is most of what a person is looking at.

The poses SHALL be carried rather than recomputed. Re-deriving where a run went would mean planning the room a second time, and a second planner is a second answer.

Scenario: A proposal carries the runs it would build

Section titled “Scenario: A proposal carries the runs it would build”
  • WHEN a room’s arrangement is proposed and its recipe builds joinery
  • THEN the proposal includes each run’s position, rotation and footprint, not merely its name and length

Scenario: A proposal for a room with no joinery is unchanged

Section titled “Scenario: A proposal for a room with no joinery is unchanged”
  • WHEN a room’s recipe builds nothing
  • THEN the proposal carries no runs, and everything else about it is as it was

Requirement: A station that is held back says so

Section titled “Requirement: A station that is held back says so”

When furnishing deliberately does not attempt a station, the outcome SHALL record that station and the reason it was not attempted, in the same place it records a station that was attempted and failed. A station that disappears from the outcome entirely is indistinguishable from one the recipe never had, so the user cannot tell a decision from an omission — and cannot ask for the thing they were not shown.

Scenario: A withheld station appears in the outcome

Section titled “Scenario: A withheld station appears in the outcome”
  • WHEN furnishing skips a station because the run it was part of did not ask for that kind of station
  • THEN the outcome lists it with a reason saying it was not attempted, rather than omitting it

Scenario: A withheld station is not reported as a failure

Section titled “Scenario: A withheld station is not reported as a failure”
  • WHEN a station is held back by the caller’s choice rather than by the room’s geometry
  • THEN its reason distinguishes the two, because “not asked for” and “would not fit” call for different things from the user

Requirement: A move can name a position instead of a coordinate

Section titled “Requirement: A move can name a position instead of a coordinate”

The assistant SHALL be able to move a placed item by naming where it should go — against a given wall, beside another item, or in the centre of the room — and the system SHALL resolve that to a legal pose for that item in that room.

Naming a position and giving a coordinate SHALL be mutually exclusive on a single move. Coordinates SHALL remain available, because a request to shift something a short distance cannot be expressed as a named position.

Scenario: A wall is named rather than measured

Section titled “Scenario: A wall is named rather than measured”
  • WHEN the assistant asks for a piece to be moved against a named wall of its room
  • THEN the piece is placed against that wall, turned to face into the room, without the assistant computing a position
  • WHEN the assistant asks for a piece to be moved a short distance by coordinate
  • THEN the move is applied as it is today
  • WHEN a move gives both a named position and a coordinate
  • THEN it is refused as malformed rather than one silently winning

Requirement: A named position falls back before it fails

Section titled “Requirement: A named position falls back before it fails”

When the named position is not usable, the system SHALL try the remaining positions along that wall, then the room’s other walls, and place the item in the first that fits — the same fallback the furnishing planner uses. Only when none fits SHALL the move be refused.

A move that lands somewhere other than first asked SHALL say where it went and that it was not the first choice, so the designer is never silently given something they did not ask for.

  • WHEN the named wall has no room for the piece but another wall does
  • THEN the piece is placed against the other wall, and the result says so

Scenario: Landing as asked is reported plainly

Section titled “Scenario: Landing as asked is reported plainly”
  • WHEN the piece fits exactly where it was asked to go
  • THEN the result reports the move without qualification
  • WHEN no position in the room can take the piece
  • THEN the move is refused, nothing is written, and the reason describes the room rather than naming one rejected position

Requirement: A refused move reports what kind of problem it is

Section titled “Requirement: A refused move reports what kind of problem it is”

A refusal SHALL carry a machine-readable kind — the room being full, the position lying outside the room or inside a wall, an opening being in the way — alongside the sentence shown to the user.

The kind exists so that the assistant and the interface can act differently on “the room is full” than on “that is not a position at all”. Prose alone cannot be branched on without parsing it, and parsing it makes a wording change a behaviour change.

Scenario: A full room and an impossible position are distinguishable

Section titled “Scenario: A full room and an impossible position are distinguishable”
  • WHEN one move is refused because another piece occupies the position and another because the position lies inside a wall
  • THEN the two refusals carry different kinds, not merely different sentences

Scenario: The sentence is still the thing the user reads

Section titled “Scenario: The sentence is still the thing the user reads”
  • WHEN a move is refused
  • THEN the user is shown the explanatory sentence, not the kind

Requirement: A move that cannot fit offers to arrange the room around it

Section titled “Requirement: A move that cannot fit offers to arrange the room around it”

When a requested move is refused only because movable furniture is in the way, the system SHALL offer to re-arrange the room around the requested position, rather than ending the turn on a refusal. The offer SHALL be a choice, never an action taken on the user’s behalf.

A move refused for a reason re-arranging cannot fix — the item would leave the room, cross a wall, block a door, or collide with something the designer placed by hand — SHALL be refused as it is today, because arranging the room differently would not make it possible.

Scenario: A blocked move offers the re-plan

Section titled “Scenario: A blocked move offers the re-plan”
  • WHEN the designer asks for a piece to be moved somewhere it does not fit, and the only things in the way are pieces the system itself placed
  • THEN the result says the piece does not fit as things stand and offers to arrange the room around it, and nothing in the document has changed

Scenario: A move that re-planning cannot rescue is still refused

Section titled “Scenario: A move that re-planning cannot rescue is still refused”
  • WHEN the requested position lies outside the room, inside a wall, or in a door’s swing
  • THEN the move is refused with that reason and no re-plan is offered, because no arrangement of the other furniture would make the position usable

Scenario: Furniture the designer placed is never moved to make room

Section titled “Scenario: Furniture the designer placed is never moved to make room”
  • WHEN the only thing obstructing a requested move is an item the designer placed or moved by hand
  • THEN the move is refused naming that item, and the re-plan is not offered — the system does not undo a person’s work to satisfy its own arrangement
  • WHEN the re-plan is offered
  • THEN no furniture has moved and nothing has been written; the arrangement exists only as a proposal until the designer accepts it

Requirement: A proposed arrangement is shown before it is applied

Section titled “Requirement: A proposed arrangement is shown before it is applied”

The system SHALL present a proposed room arrangement as a drawing of the room, to scale, showing each piece’s footprint in its proposed position within the room’s own boundary, before any of it is written. The piece the designer asked to move SHALL be distinguishable from the pieces being moved to accommodate it.

The drawing SHALL show the arrangement being offered — not the room as it stands — so that accepting holds no surprise.

Scenario: The proposal is drawn on the room’s boundary

Section titled “Scenario: The proposal is drawn on the room’s boundary”
  • WHEN a re-planned arrangement is offered
  • THEN it is shown as a plan of that room, with the room’s outline and each piece’s footprint at its proposed position and orientation
  • WHEN the proposal is shown
  • THEN the piece the designer asked to move is distinguished from the pieces that moved to make room for it, so it is clear which position was asked for and which were derived

Scenario: Pieces that could not be replaced are reported

Section titled “Scenario: Pieces that could not be replaced are reported”
  • WHEN an arrangement cannot fit every piece it moved
  • THEN the proposal says which pieces would be left out and why, before the designer accepts — rather than reporting the loss afterwards

Scenario: Accepting applies exactly what was shown

Section titled “Scenario: Accepting applies exactly what was shown”
  • WHEN the designer accepts a proposed arrangement
  • THEN the furniture is placed as drawn, with no further planning between the drawing and the writing
  • WHEN the designer rejects a proposed arrangement, or leaves it without accepting
  • THEN the room is exactly as it was, with nothing written and nothing to undo

Scenario: An accepted arrangement is one undo step

Section titled “Scenario: An accepted arrangement is one undo step”
  • WHEN the designer accepts an arrangement that moved several pieces
  • THEN a single undo returns every one of them to where it was