diff --git a/packages/layout/README.md b/packages/layout/README.md
new file mode 100644
index 0000000..27d5fbe
--- /dev/null
+++ b/packages/layout/README.md
@@ -0,0 +1,141 @@
+# Layout
+
+`@workspace/layout` 提供路由无关的应用级布局。`AppLayout` 以内容区为核心，并按需组合 Header、Navigation Rail、Sidebar、Aside 和 Footer。
+
+## 安装样式源
+
+在应用的全局样式中导入：
+
+```css
+@import "@workspace/layout/globals.css";
+```
+
+## 布局模型
+
+```text
++-------------------------------------+
+| header | headerStart="rail"
++------+---------+---------+----------+
+| | header | headerStart="sidebar"
+| +---------+---------+----------+
+| | | header | headerStart="content"
+| | +---------+----------+
+| | | | |
+| rail | sidebar | content | |
+| | +---------+ aside |
+| | | footer | | footerStart="content"
+| +---------+---------+ |
+| | footer | | footerStart="sidebar"
++------+-------------------+----------+
+```
+
+图中的多个 Header 和 Footer 表示可选位置，不会同时渲染。`children` 是唯一必需的内容区，其他区域均为可选 slot：
+
+- `rail`：最外侧的一级导航，类似 Activity Bar。
+- `sidebar`：当前一级导航下的导航或工作区上下文。
+- `aside`：AI、文档、检查器等内容辅助区域。
+- `header`：右边界始终包含有效的 `aside`。
+- `footer`：始终属于中心工作区，不会延伸到 `rail` 或 `aside` 下方。
+
+## 基本用法
+
+Slot 可以接收已经创建的 React 节点，也可以接收无必需属性的组件定义。组件定义在 `AppLayout` 的 Provider 内创建，因此可以调用 `useLayoutConfig`。
+
+```tsx
+import { AppLayout } from "@workspace/layout"
+
+export function Application() {
+ return (
+ }
+ aside={AssistantPanel}
+ footer={StatusBar}
+ defaultLayout={{
+ asideOpen: true,
+ footerStart: "sidebar",
+ headerStart: "sidebar",
+ }}
+ >
+
+
+ )
+}
+```
+
+## LayoutConfig
+
+`LayoutConfig` 是扁平、可序列化的完整快照；`layout` 和 `defaultLayout` 接收 `Partial`。
+
+```ts
+interface LayoutConfig {
+ asideEnabled: boolean
+ asideOpen: boolean
+ footerStart: "sidebar" | "content"
+ headerStart: "rail" | "sidebar" | "content"
+ sidebarCollapsible: boolean
+ sidebarOpen: boolean
+}
+```
+
+默认值：
+
+```ts
+const defaultLayoutConfig = {
+ asideEnabled: true,
+ asideOpen: false,
+ footerStart: "content",
+ headerStart: "rail",
+ sidebarCollapsible: true,
+ sidebarOpen: true,
+}
+```
+
+- 提供 `layout` 时采用受控模式，交互后通过 `onLayoutChange` 返回完整快照。
+- 未提供 `layout` 时采用非受控模式，以 `defaultLayout` 或默认配置初始化。
+- 区域暂时不可用只影响有效布局，不会覆盖配置中保存的用户偏好。
+
+## useLayoutConfig
+
+区域组件可以读取布局状态并触发布局更新：
+
+```tsx
+import { useLayoutConfig } from "@workspace/layout"
+
+export function AppHeader() {
+ const {
+ layout,
+ setAsideOpen,
+ setSidebarOpen,
+ toggleAside,
+ toggleSidebar,
+ updateLayout,
+ } = useLayoutConfig()
+
+ // Render application controls.
+}
+```
+
+Hook 必须在 `AppLayout` 子树内调用。`updateLayout` 接收局部配置或根据当前完整配置生成局部配置的函数。
+
+## 自动内移
+
+`headerStart` 和 `footerStart` 表示期望位置。布局会根据当前实际可见的区域计算有效位置，但不会改写原配置：
+
+- `headerStart="rail"` 表示全局 Header；没有 Rail 时从第一个实际存在的区域开始。
+- 只有 Rail 与 Sidebar 同时可见时，`headerStart="sidebar"` 和 `footerStart="sidebar"` 才会生效。
+- 其他情况下，`"sidebar"` 自动内移为 `"content"`。
+- Aside 始终贯穿中心工作区高度，不参与 Footer 范围。
+
+## 尺寸
+
+可以通过 CSS 自定义属性调整三个辅助列：
+
+```css
+.application-layout {
+ --layout-rail-width: 4rem;
+ --layout-sidebar-width: 18rem;
+ --layout-aside-width: 22rem;
+}
+```
\ No newline at end of file
diff --git a/packages/layout/docs/en-US/advanced/configuration.mdx b/packages/layout/docs/en-US/advanced/configuration.mdx
new file mode 100644
index 0000000..d77c640
--- /dev/null
+++ b/packages/layout/docs/en-US/advanced/configuration.mdx
@@ -0,0 +1,40 @@
+---
+title: Configuration and effective layout
+description: Manage controlled configuration, persistent preferences, and automatic region resolution.
+order: 20
+toc:
+ - id: controlled
+ title: Controlled and uncontrolled
+ - id: effective
+ title: Effective layout
+ - id: persistence
+ title: Persistence
+---
+
+## Controlled and uncontrolled {#controlled}
+
+Without `layout`, `AppLayout` owns its state:
+
+```tsx
+
+
+
+```
+
+After supplying `layout`, the caller must save each new snapshot from `onLayoutChange`:
+
+```tsx
+
+
+
+```
+
+## Effective layout {#effective}
+
+Configuration stores user intent, while the effective layout controls the current rendering. For example, `asideOpen` can remain `true` while a missing Aside slot or `asideEnabled: false` prevents the Aside from rendering. When `sidebarCollapsible` is `false`, the Sidebar remains visible even if the stored `sidebarOpen` value is `false`.
+
+Header and Footer starts follow the same principle. `"sidebar"` only takes effect while both the Rail and Sidebar are visible; otherwise it moves inward to `"content"`.
+
+## Persistence {#persistence}
+
+The effective layout never writes back into configuration, so temporarily missing regions do not clear user preferences. An application can persist the complete `LayoutConfig` through `@workspace/preferences` in `onLayoutChange`, then supply it through `layout` when loading.
diff --git a/packages/layout/docs/en-US/examples/workspace.mdx b/packages/layout/docs/en-US/examples/workspace.mdx
new file mode 100644
index 0000000..3a9eb48
--- /dev/null
+++ b/packages/layout/docs/en-US/examples/workspace.mdx
@@ -0,0 +1,54 @@
+---
+title: Workspace layout
+description: Compose navigation, content, and an AI assistance panel.
+order: 30
+toc:
+ - id: layout
+ title: Create the layout
+ - id: controls
+ title: Add controls
+---
+
+## Create the layout {#layout}
+
+```tsx
+export function Workspace() {
+ return (
+
+
+
+ )
+}
+```
+
+After the user collapses the Sidebar, Header and Footer regions starting at `"sidebar"` automatically move inward to the content column without retaining an empty grid track.
+
+## Add controls {#controls}
+
+```tsx
+function WorkspaceHeader() {
+ const { layout, toggleAside, toggleSidebar } = useLayoutConfig()
+
+ return (
+
+ {layout.sidebarCollapsible && (
+
+ )}
+ {layout.asideEnabled && }
+
+ )
+}
+```
+
+The control component does not need callbacks threaded through the application; component slots are created inside the layout context.
diff --git a/packages/layout/docs/en-US/guide/setup.mdx b/packages/layout/docs/en-US/guide/setup.mdx
new file mode 100644
index 0000000..82420ba
--- /dev/null
+++ b/packages/layout/docs/en-US/guide/setup.mdx
@@ -0,0 +1,52 @@
+---
+title: Set up the application layout
+description: Configure the style source and compose application layout regions.
+order: 10
+toc:
+ - id: styles
+ title: Import the style source
+ - id: compose
+ title: Compose regions
+ - id: sizes
+ title: Adjust sizes
+---
+
+## Import the style source {#styles}
+
+Import the Layout Tailwind source from the application stylesheet:
+
+```css
+@import "@workspace/layout/globals.css";
+```
+
+## Compose regions {#compose}
+
+`AppLayout` accepts React nodes or component definitions without required props. Pass a node when the region needs business props, or pass a component definition when it should read layout state from context.
+
+```tsx
+}
+ aside={AssistantPanel}
+ footer={StatusBar}
+>
+
+
+```
+
+Component definitions are created inside the `AppLayout` provider, so `AppHeader` and `AssistantPanel` can call `useLayoutConfig`.
+
+## Adjust sizes {#sizes}
+
+Use CSS custom properties to size the supporting columns:
+
+```css
+.application-layout {
+ --layout-rail-width: 4rem;
+ --layout-sidebar-width: 18rem;
+ --layout-aside-width: 22rem;
+}
+```
+
+Pass that class to `AppLayout`. The content column always consumes the remaining space and can shrink to zero width.
diff --git a/packages/layout/docs/en-US/overview.mdx b/packages/layout/docs/en-US/overview.mdx
new file mode 100644
index 0000000..42ce640
--- /dev/null
+++ b/packages/layout/docs/en-US/overview.mdx
@@ -0,0 +1,67 @@
+---
+title: Overview
+description: Build application layouts with optional regions and persistent configuration.
+order: 1
+toc:
+ - id: role
+ title: Package role
+ - id: regions
+ title: Layout regions
+ - id: config
+ title: Configuration and hook
+---
+
+## Package role {#role}
+
+`@workspace/layout` provides the router-neutral `AppLayout`. It composes an application header, navigation rail, sidebar, content, aside, and footer with CSS Grid, then resolves the effective grid from the currently visible regions. The package does not create navigation data, constrain the router, or persist user preferences.
+
+Import the Tailwind source from the application stylesheet:
+
+```css
+@import "@workspace/layout/globals.css";
+```
+
+## Layout regions {#regions}
+
+```tsx
+import { AppLayout } from "@workspace/layout"
+
+export function Application() {
+ return (
+
+
+
+ )
+}
+```
+
+`children` is the only required content region. The sidebar can collapse, while the aside suits assistants, documentation, and inspectors. The header can begin at the rail, sidebar, or content; the footer can begin at the sidebar or content. A missing preceding region automatically moves the effective start inward.
+
+## Configuration and hook {#config}
+
+`layout` accepts `Partial`. Supplying it enables controlled mode; otherwise `AppLayout` initializes internal state from `defaultLayout`. Region components can call `useLayoutConfig`:
+
+```tsx
+import { useLayoutConfig } from "@workspace/layout"
+
+export function AppHeader() {
+ const { layout, toggleAside, toggleSidebar } = useLayoutConfig()
+
+ return (
+
+ )
+}
+```
+
+Temporarily hiding or disabling a region only changes the effective layout; it does not overwrite the original preference stored in `LayoutConfig`. The configuration can therefore integrate safely with `@workspace/preferences`.
diff --git a/packages/layout/docs/meta.yaml b/packages/layout/docs/meta.yaml
new file mode 100644
index 0000000..abc2c0c
--- /dev/null
+++ b/packages/layout/docs/meta.yaml
@@ -0,0 +1,6 @@
+group: application
+order: 5
+label: Layout
+description:
+ zh-Hans: 通过可选区域、可持久化配置和自动网格解析构建应用级布局。
+ en-US: Build application layouts with optional regions, persistent configuration, and automatic grid resolution.
diff --git a/packages/layout/docs/zh-Hans/advanced/configuration.mdx b/packages/layout/docs/zh-Hans/advanced/configuration.mdx
new file mode 100644
index 0000000..63d57cf
--- /dev/null
+++ b/packages/layout/docs/zh-Hans/advanced/configuration.mdx
@@ -0,0 +1,40 @@
+---
+title: 配置与有效布局
+description: 管理受控配置、持久化偏好和区域自动内移。
+order: 20
+toc:
+ - id: controlled
+ title: 受控与非受控
+ - id: effective
+ title: 有效布局
+ - id: persistence
+ title: 持久化
+---
+
+## 受控与非受控 {#controlled}
+
+未提供 `layout` 时，`AppLayout` 使用内部状态：
+
+```tsx
+
+
+
+```
+
+提供 `layout` 后，调用方必须在 `onLayoutChange` 中保存新快照：
+
+```tsx
+
+
+
+```
+
+## 有效布局 {#effective}
+
+配置保存用户意图，有效布局负责当前渲染。例如 `asideOpen` 可以为 `true`，但没有 Aside slot 或 `asideEnabled` 为 `false` 时不会渲染 Aside。`sidebarCollapsible` 为 `false` 时，即使保存的 `sidebarOpen` 为 `false`，Sidebar 也会保持显示。
+
+Header 和 Footer 的起始位置遵循同样原则。只有 Rail 与 Sidebar 同时可见时，`"sidebar"` 才会生效；否则自动内移到 `"content"`。
+
+## 持久化 {#persistence}
+
+有效布局不会反向修改配置，因此临时缺少某个区域不会清除用户偏好。应用可以在 `onLayoutChange` 中把完整 `LayoutConfig` 写入 `@workspace/preferences`，并在加载时通过 `layout` 传回。
diff --git a/packages/layout/docs/zh-Hans/examples/workspace.mdx b/packages/layout/docs/zh-Hans/examples/workspace.mdx
new file mode 100644
index 0000000..63991b7
--- /dev/null
+++ b/packages/layout/docs/zh-Hans/examples/workspace.mdx
@@ -0,0 +1,54 @@
+---
+title: 工作区布局
+description: 组合导航、内容和 AI 辅助面板。
+order: 30
+toc:
+ - id: layout
+ title: 创建布局
+ - id: controls
+ title: 添加控制
+---
+
+## 创建布局 {#layout}
+
+```tsx
+export function Workspace() {
+ return (
+
+
+
+ )
+}
+```
+
+当用户折叠 Sidebar 后，Header 和 Footer 中以 `"sidebar"` 为起点的区域会自动内移到内容列，网格不会保留空轨道。
+
+## 添加控制 {#controls}
+
+```tsx
+function WorkspaceHeader() {
+ const { layout, toggleAside, toggleSidebar } = useLayoutConfig()
+
+ return (
+
+ {layout.sidebarCollapsible && (
+
+ )}
+ {layout.asideEnabled && }
+
+ )
+}
+```
+
+控制组件不需要从应用逐层接收回调；组件型 slot 会在布局上下文内部创建。
diff --git a/packages/layout/docs/zh-Hans/guide/setup.mdx b/packages/layout/docs/zh-Hans/guide/setup.mdx
new file mode 100644
index 0000000..0c89db7
--- /dev/null
+++ b/packages/layout/docs/zh-Hans/guide/setup.mdx
@@ -0,0 +1,52 @@
+---
+title: 设置应用布局
+description: 配置样式源并组合应用布局区域。
+order: 10
+toc:
+ - id: styles
+ title: 导入样式源
+ - id: compose
+ title: 组合区域
+ - id: sizes
+ title: 调整尺寸
+---
+
+## 导入样式源 {#styles}
+
+在应用全局样式中导入 Layout 的 Tailwind 源：
+
+```css
+@import "@workspace/layout/globals.css";
+```
+
+## 组合区域 {#compose}
+
+`AppLayout` 接受 React 节点或无必需属性的组件定义。需要业务属性时传入节点；需要组件从布局上下文读取状态时，可以直接传入组件定义。
+
+```tsx
+}
+ aside={AssistantPanel}
+ footer={StatusBar}
+>
+
+
+```
+
+组件定义会在 `AppLayout` 的 Provider 内创建，因此 `AppHeader` 和 `AssistantPanel` 可以调用 `useLayoutConfig`。
+
+## 调整尺寸 {#sizes}
+
+通过 CSS 自定义属性调整辅助列宽度：
+
+```css
+.application-layout {
+ --layout-rail-width: 4rem;
+ --layout-sidebar-width: 18rem;
+ --layout-aside-width: 22rem;
+}
+```
+
+把该类名传给 `AppLayout`。内容列始终使用剩余空间，并允许收缩到零宽。
diff --git a/packages/layout/docs/zh-Hans/overview.mdx b/packages/layout/docs/zh-Hans/overview.mdx
new file mode 100644
index 0000000..b85b8ec
--- /dev/null
+++ b/packages/layout/docs/zh-Hans/overview.mdx
@@ -0,0 +1,67 @@
+---
+title: 概览
+description: 使用可选区域和可持久化配置构建应用级布局。
+order: 1
+toc:
+ - id: role
+ title: 包的职责
+ - id: regions
+ title: 布局区域
+ - id: config
+ title: 配置与 Hook
+---
+
+## 包的职责 {#role}
+
+`@workspace/layout` 提供路由无关的 `AppLayout`。它通过 CSS Grid 组合应用 Header、Navigation Rail、Sidebar、内容区、Aside 和 Footer，并根据实际可见区域自动计算有效网格。包不创建导航数据，不限制路由器，也不持久化用户偏好。
+
+在应用全局样式中导入 Tailwind 源：
+
+```css
+@import "@workspace/layout/globals.css";
+```
+
+## 布局区域 {#regions}
+
+```tsx
+import { AppLayout } from "@workspace/layout"
+
+export function Application() {
+ return (
+
+
+
+ )
+}
+```
+
+`children` 是唯一必需的内容区。Sidebar 可以折叠，Aside 适合 AI、文档和检查器等辅助功能。Header 可以从 Rail、Sidebar 或内容区开始；Footer 可以从 Sidebar 或内容区开始。缺少前置区域时，起始位置会自动向内容区内移。
+
+## 配置与 Hook {#config}
+
+`layout` 接收 `Partial`。提供它时使用受控模式；否则 `AppLayout` 通过 `defaultLayout` 初始化内部状态。区域组件可以调用 `useLayoutConfig`：
+
+```tsx
+import { useLayoutConfig } from "@workspace/layout"
+
+export function AppHeader() {
+ const { layout, toggleAside, toggleSidebar } = useLayoutConfig()
+
+ return (
+
+ )
+}
+```
+
+临时隐藏或禁用区域只影响当前有效布局，不会覆盖 `LayoutConfig` 中保存的原始偏好，因此配置可以安全接入 `@workspace/preferences`。