> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_21/session_01_expansion_state_foundation.md).

# Session 01: Expansion State Foundation

**Session ID**: `phase21-session01-expansion-state-foundation` **Package**: apps/web **Status**: Complete **Completed**: 2026-06-29 **Estimated Tasks**: \~12-18 **Estimated Duration**: 2-4 hours

***

## Objective

Establish one canonical transient state model for focused bottom-rail expansion.

***

## Scope

### In Scope (MVP)

* Add a typed bottom-rail surface id for Quest Board, Orchestration, and War Room.
* Add `expandedBottomRailSurfaceId` and a setter to `apps/web/src/store/useSettingsStore.ts`.
* Keep expansion state out of the persisted settings snapshot.
* Update store reset helpers and focused settings tests.
* Document the state contract in code only where needed for clarity.

### Out of Scope

* Rendering the expanded shell host.
* Changing Orchestration header labels.
* Quest Board or War Room panel behavior changes.

***

## Prerequisites

* [x] Phase 21 PRD reviewed.
* [x] Current settings store persistence behavior understood.
* [x] Existing tests that reset `DEFAULT_SETTINGS` identified.

***

## Deliverables

1. Transient bottom-rail expansion state in `useSettingsStore`.
2. Focused store tests for default, set, clear, reset, and persistence behavior.
3. No changes to domain stores or persisted user preferences.

***

## Folded Source Details

The folded source findings identified expansion as transient shell/UI state, not domain state and not persisted user preference. This session owns the canonical state foundation so later panel and shortcut work does not invent parallel booleans.

Implementation details to preserve:

* Define a bottom-rail-only surface type such as `BottomRailSurfaceId = "quest-board" | "orchestration" | "war-room"`.
* Add `expandedBottomRailSurfaceId: BottomRailSurfaceId | null` and `setExpandedBottomRailSurfaceId(...)` in `apps/web/src/store/useSettingsStore.ts`.
* Keep the field out of the persisted settings snapshot. It belongs with existing transient overlay booleans such as `replayPanelOpen`, `commandPaletteOpen`, `settingsDrawerOpen`, `heatmapOpen`, `standingsOpen`, `leaderboardOpen`, `toolUsageOpen`, and `complexityOverlayOpen`.
* Update test reset helpers that recreate `DEFAULT_SETTINGS` so expanded surface state cannot leak between tests.
* Do not use `useGameStore` for this UI-only state; `useGameStore` already owns domain and command-center state such as `commandCenter.activeTab` and `commandCenter.selectedDetail`.

End-to-end delivery bar for this session:

* The user-facing outcome is not visible yet, so this session must not claim panel expansion is shipped.
* The proved outcome is that all later sessions have one canonical state source for opening, replacing, and clearing focused bottom-rail surfaces.
* Tests must prove set/clear/reset/persistence behavior with real store execution, not type declarations alone.

***

## Success Criteria

* [x] `expandedBottomRailSurfaceId` defaults to `null`.
* [x] The setter accepts only the defined bottom-rail surface ids or `null`.
* [x] Persisted settings output excludes the transient expansion state.
* [x] Existing settings tests pass with no state leakage between tests.
* [x] No UI claims are made yet; this session ships only the state foundation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_21/session_01_expansion_state_foundation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.