AI features
Generated from
openspec/specs/ai-features/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”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.
Requirements
Section titled “Requirements”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
sceneContextfor 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 /chatis processing a turn that ends in a tool call - THEN the client receives incremental
textSSE events as the model composes its response, followed by a single terminaldoneevent carryingstopReasonand the fullcontent(including any tool_use blocks) — noinput_json_deltaor 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 fromdone.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
Scenario: Auto-turns are capped
Section titled “Scenario: Auto-turns are capped”- WHEN a tool_result is posted back to
/chatand the model immediately requests another tool call - THEN
ChatPanelcontinues auto-firing follow-up turns only up toMAX_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_openingorapply_style_presettool 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_roomonce 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
chatcredit pool is empty and a non-admin user sends a chat message - THEN
POST /chatreturns 402insufficient_creditswithout calling the model
Scenario: Refund on upstream failure
Section titled “Scenario: Refund on upstream failure”- 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_KEYis not set in the current environment - THEN
POST /chatreturns 503chat_not_configured
Scenario: Restyle unavailable without a ComfyCloud key
Section titled “Scenario: Restyle unavailable without a ComfyCloud key”- WHEN
COMFY_API_KEYis 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.
Scenario: Submit and poll a restyle job
Section titled “Scenario: Submit and poll a restyle job”- WHEN a designer captures a walkthrough snapshot and submits it with a style prompt via
WalkthroughPhotos - THEN
POST /walkthrough-restylesinserts arestyle_jobsrow, mirrors the input image to R2, and submits the job to ComfyCloud; the client pollsGET /walkthrough-restyles/:jobIduntil the job reaches a terminal status
Scenario: Restyle requires an active org
Section titled “Scenario: Restyle requires an active org”- 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/:jobIddoes not yet report anoutputUrl
Scenario: Output is served once mirrored
Section titled “Scenario: Output is served once mirrored”- WHEN a restyle job’s output has been mirrored to R2 and the row marked successful
- THEN
GET /walkthrough-restyles/:jobId/output.pngproxies 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/generatewith 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 onprojects.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
ChatPanelfetches the profile best-effort and includes it insceneContext.styleProfile, which the/chatroute 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
materialsorthemesis 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
Scenario: Style never overrides fit
Section titled “Scenario: Style never overrides fit”- 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 onprojects.styleProfilefrom their answers alone
Scenario: Both paths write the same shape
Section titled “Scenario: Both paths write the same shape”- 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
palettedoes 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
Scenario: The result offers actions
Section titled “Scenario: The result offers actions”- 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
Scenario: No model call and no charge
Section titled “Scenario: No model call and no charge”- 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.
Scenario: No wall is long enough
Section titled “Scenario: No wall is long enough”- 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
Scenario: Wall units follow the legs
Section titled “Scenario: Wall units follow the legs”- 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
Scenario: A nudge still works
Section titled “Scenario: A nudge still works”- WHEN the assistant asks for a piece to be moved a short distance by coordinate
- THEN the move is applied as it is today
Scenario: Naming both is refused
Section titled “Scenario: Naming both is refused”- 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.
Scenario: The requested wall is occupied
Section titled “Scenario: The requested wall is occupied”- 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
Scenario: Nothing fits anywhere
Section titled “Scenario: Nothing fits anywhere”- 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
Scenario: The offer is not the action
Section titled “Scenario: The offer is not the action”- 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
Scenario: The requested piece is marked
Section titled “Scenario: The requested piece is marked”- 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
Scenario: Rejecting changes nothing
Section titled “Scenario: Rejecting changes nothing”- 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