@soederpop/luca 0.0.6 → 0.0.8

package/docs/bootstrap/templates/example-feature.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    example: typeof Example
+  }
+}
+
+const ExampleStateSchema = FeatureStateSchema.extend({
+  greetCount: z.number().default(0).describe('Number of times greet() has been called'),
+})
+type ExampleState = z.infer<typeof ExampleStateSchema>
+
+const ExampleOptionsSchema = FeatureOptionsSchema.extend({})
+type ExampleOptions = z.infer<typeof ExampleOptionsSchema>
+
+/**
+ * An example feature demonstrating the luca feature pattern.
+ *
+ * Discovered automatically by `container.helpers.discoverAll()`
+ * and available as `container.feature('example')`.
+ *
+ * To learn more: `luca scaffold feature --tutorial`
+ *
+ * @example
+ * ```typescript
+ * const example = container.feature('example')
+ * example.greet('Luca') // => "Hello, Luca! (greeting #1)"
+ * ```
+ */
+export class Example extends Feature<ExampleState, ExampleOptions> {
+  static override shortcut = 'features.example' as const
+  static override stateSchema = ExampleStateSchema
+  static override optionsSchema = ExampleOptionsSchema
+  static override description = 'An example feature demonstrating the luca feature pattern'
+  static { Feature.register(this, 'example') }
+
+  /**
+   * A simple method to show the feature works.
+   * @param name - Name to greet
+   * @returns Greeting string
+   */
+  greet(name = 'World') {
+    const count = (this.state.get('greetCount') || 0) + 1
+    this.state.set('greetCount', count)
+    return `Hello, ${name}! (greeting #${count})`
+  }
+}
+
+export default Example

package/docs/bootstrap/templates/health-endpoint.ts

@@ -0,0 +1,15 @@
+/**
+ * Health check endpoint.
+ * Accessible at GET /api/health when you run `luca serve`.
+ */
+export const path = '/api/health'
+export const description = 'Health check endpoint'
+export const tags = ['health']
+
+export async function get(_params: any, ctx: any) {
+  return {
+    status: 'ok',
+    timestamp: Date.now(),
+    uptime: process.uptime(),
+  }
+}

package/docs/bootstrap/templates/luca-cli.ts

@@ -0,0 +1,25 @@
+/**
+ * luca.cli.ts — Project-level CLI customization
+ *
+ * This file is automatically loaded by the `luca` CLI before any command runs.
+ * Use it to:
+ *
+ * - Discover project-level helpers (features, commands, endpoints)
+ * - Register custom context variables accessible in `luca eval`
+ * - Set up project-specific container configuration
+ *
+ * Exports:
+ *   main(container)    — called at CLI startup, before command execution
+ *   onStart(container) — called when the container's 'started' event fires
+ *
+ * Example:
+ *   export async function main(container: any) {
+ *     await container.helpers.discoverAll()
+ *     container.addContext('myFeature', container.feature('myFeature'))
+ *   }
+ */
+
+export async function main(container: any) {
+  // Discover project-level helpers (commands/, features/, endpoints/)
+  await container.helpers.discoverAll()
+}

package/docs/bootstrap/templates/runme.md

@@ -0,0 +1,54 @@
+# Runnable Markdown
+
+The `luca` CLI allows you to run markdown blocks as long as they're tagged with `ts` in the language.
+
+```ts
+const banner = ui.banner('LUCA', {
+    font: 'Puffy',
+    colors: ['red','white','blue']
+})
+
+ui.print(banner)
+```
+
+What is kind of cool is ( so long as there's no top-level-await in the block ) the context will preserve:
+
+```ts
+if(typeof banner === 'undefined') {
+    ui.print.red('uh oh, something broke.')
+}
+```
+
+You can skip blocks too with the skip tag in the language of the fenced block
+
+```ts skip
+console.log('Not gonna say anything')
+```
+
+Did you hear something? No.
+
+Something even cooler is the ability to render React blocks.  This makes luca kind of like a poor man's MDX.  I just define some Blocks in the markdown by creating an h2 `## Blocks` section with a fenced codeblock that uses `tsx`. The `ink.components` and `ink.React` globals are injected into the scope.
+
+## Blocks
+
+```tsx
+const { Box, Text } = ink.components
+const React = ink.React
+
+function Greeting({ name, role }) {
+  return (
+    <Box borderStyle="round" padding={1}>
+      <Text color="green" bold>Hello {name}!</Text>
+      <Text dimColor> ({role})</Text>
+    </Box>
+  )
+}
+```
+
+## Rendering React Blocks
+
+Then I can use the Blocks in code.
+
+```ts
+await render('Greeting', { name: 'Jon', role: 'Humble Servant' })
+```

package/docs/challenges/caching-proxy.md

@@ -0,0 +1,16 @@
+# Build a Caching Proxy
+
+Create `luca proxy` that starts a local HTTP server which proxies incoming requests to a configurable upstream URL, caching responses with a configurable TTL (default 60 seconds).
+
+Support these flags:
+
+- `luca proxy --upstream https://jsonplaceholder.typicode.com` — set the upstream
+- `luca proxy --ttl 120` — cache TTL in seconds
+- `luca proxy --flush` — clear the cache and exit
+- `luca proxy --stats` — show cache hit/miss ratio and exit
+
+When running, every request to `localhost:<port>/anything` should proxy to `<upstream>/anything`, serving from cache on hit.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/content-db-round-trip.md

@@ -0,0 +1,14 @@
+# Content DB Round-Trip
+
+Populate a `docs/recipes/` collection with 5 recipe documents. Each document should have frontmatter with `title`, `tags` (array), `difficulty` (easy/medium/hard), and a markdown body with ingredients and steps.
+
+Create two commands:
+
+- `luca recipes search <term>` — queries the collection by tag or title match and prints matching recipes
+- `luca recipes export` — writes a `recipes-summary.json` file with all recipe titles, tags, and difficulty levels
+
+All document access must go through the container's document system, not raw file reads.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/custom-command.md

@@ -0,0 +1,9 @@
+# Build a custom command
+
+Build a custom command with luca called `hello`
+
+I should be able to run the command `luca hello $whatever` and it should output the word $whatever with an ascii art gradient, using only the features available in luca.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/file-watcher-pipeline.md

@@ -0,0 +1,11 @@
+# Build a File Watcher Pipeline
+
+Watch a folder called `inbox/` for new `.json` files. When a new file appears, validate that it has a `name` and `email` field. Move valid files to `inbox/valid/` and invalid files to `inbox/invalid/`.
+
+Create `luca watch` to start the watcher and `luca status` to report how many files have been processed, how many were valid, and how many were invalid.
+
+Include a `luca seed` command that drops a few sample `.json` files into `inbox/` so you can test it.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/grep-audit-report.md

@@ -0,0 +1,15 @@
+# Grep Audit Report
+
+Build `luca audit <path>` that scans a codebase at the given path and finds:
+
+- TODO and FIXME comments
+- `console.log` statements
+- Hardcoded secret patterns (strings that look like API keys, tokens, passwords in assignments)
+
+Generate a markdown report at `docs/reports/audit-<timestamp>.md` summarizing the findings with file paths and line numbers.
+
+Support `luca audit <path> --json` for machine-readable output instead of markdown.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/multi-feature-dashboard.md

@@ -0,0 +1,14 @@
+# Build a Multi-Feature Dashboard
+
+Create a `luca dashboard` command that displays a live-updating terminal UI showing:
+
+- Git status: current branch, number of dirty files
+- Cache stats: number of cached entries
+- OS info: CPU usage, free memory
+- Network: whether https://example.com is reachable
+
+The dashboard should refresh every 2 seconds with a nice terminal layout.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/process-orchestrator.md

@@ -0,0 +1,17 @@
+# Process Orchestrator
+
+Build `luca dev` that starts 3 processes simultaneously:
+
+1. An HTTP API server on port 3000
+2. A WebSocket server on port 3001
+3. A file watcher that logs changes in the project directory
+
+Multiplex their logs to stdout with color-coded prefixes (e.g. `[API]`, `[WS]`, `[WATCH]`). Gracefully shut down all processes on ctrl+c.
+
+Support `luca dev --only api,ws` to start a subset of the processes.
+
+Create a simple endpoint and websocket handler so there's something to actually hit when testing.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/rest-api-server-with-client.md

@@ -0,0 +1,12 @@
+# Build a REST server with a matching REST Client
+
+Create a command `luca start` which will use a custom luca express server you build and start it.
+
+Also create a rest client that can call the methods it exposes.
+
+The `luca connect` command should use the client and verify that all the servers endpoints work.
+
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/script-runner-with-vm.md

@@ -0,0 +1,11 @@
+# Script Runner with VM
+
+Create a `scripts/` folder with a few `.ts` files that each export a `run()` function. These scripts should do simple things — format a date, generate a UUID, compute a hash of some input.
+
+Build a `luca exec <scriptName>` command that loads and runs the named script in a sandboxed environment. The script should have access to the container but not direct filesystem access.
+
+Add `luca exec --list` to show all available scripts with a short description parsed from a comment or export in each file.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/simple-rest-api.md

@@ -0,0 +1,15 @@
+---
+lastRanAt: 1773554828927
+durationMs: 601701
+outputTokens: 1646
+---
+
+# Build an API
+
+I should be able to serve the api with `luca serve`
+
+The API should use sqlite to serve an example api that lets me browse authors and books.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/websocket-serve-and-client.md

@@ -0,0 +1,11 @@
+# Build a websocket server with a matching websocket client
+
+Use the luca framework to build a websocket server you can start with a `luca start` command.
+
+Also build a websocket based client that can connect to that server and speak the same language ( as opposed to just raw websocket calls )
+
+Create a command called `luca connect` that uses this client and verifies that the server responds as expected.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/challenges/yaml-config-system.md

@@ -0,0 +1,14 @@
+# YAML Config System
+
+Build a command suite for managing project configuration stored in `luca.config.yaml`:
+
+- `luca config set <key> <value>` — set a config value (support nested keys like `server.port`)
+- `luca config get <key>` — get a config value
+- `luca config list` — print the full config as a formatted table
+- `luca config delete <key>` — remove a key
+
+Create the config file if it doesn't exist.
+
+## After you are done
+
+Write a LESSONS.md in the attempt folder that describes what you learned, what you struggled with, and what you could have been supplied with up front either in the CLAUDE.md or in the skills that come with luca so you could achieve the goal quicker and with less trouble.

package/docs/command-system-overhaul.md

@@ -0,0 +1,94 @@
+# Command System Overhaul
+
+The command system was pretty much 100% vibe coded and not reviewed.  It was only until the first round of evals that I noticed some issues with it and dug into the code and noticed a few things with its implementation that are not consistent with the rest of the project.
+
+My main issue is it doesn't actually use the luca Registry, the Command is not even a subclass of Helper, even though it is easily one of the most obvious examples, however there are quirks to it that let me empathize with the agent for its choices, so I want to resolve those conflicts so we can arrive at the correct design.
+
+## Original Vision For Commands
+
+1) For a user of the compiled `luca` binary, any `commands/:commandName.ts` will be available as `luca commandName` 
+2) The luca framework itself comes with core commands in `src/commands/*` that are bundled with the `luca` binary from bun
+3) A user can also have `~/.luca/commands` folder which gets picked up
+4) commands can export a zod schema that can be used for validation, documentation for CLI help screens
+
+## Command Helper Options / State 
+
+A Command's constructor options are higher level things about the environment the command is being invoked in:
+
+- target ( cli (output to stdout, stderr etc), headless (e.g. run through the js api in code, stdout, stderr needs to be captured and returned) 
+
+
+## Developer Experience Requirements
+
+Unlike features, clients, servers, which necessarily require a lot more forethought, a command should be very quick to author
+
+for this reason, there needs to be a way that we can dynamically generate Command helper subclasses, without requiring the user to go through the ceremony of doing that.
+
+Instead, a command module should be able to simply export a couple of expected named objects / types, and have the Command helper subclass generated and registered in the command registry at runtime.
+
+## Idea for General Reusable DX Feature
+
+This approach will allow us to accomplish the DX requirement for commands in a way that could make authoring every type of helper simpler as well, without having to modify the core class based implementation. 
+
+Given a typescript module called serve
+
+
+```ts
+import type { SimpleCommand } from '@soederpop/luca'
+
+// SimpleCommand is a ts generic that makes it simpler to construct the actual class ServeCommand<CommandHelperOptions,COmmandHelperState> since all commands share the same base constructor options and have the same state, but we will need to capture
+// the run options schema 
+declare module '@soederpop/luca' {
+  interface AvailableCommands {
+    serve: typeof Command  
+  }
+}
+
+
+// container is gonna be global here if they don't import anything
+// because this module will be run through the container's vm instead of being directly imported
+const runOptionsSchema = z.object({
+
+})
+
+export type ServeRunOptions = z.infer<typeof runOptionsSchema> 
+
+export async function run(options: ServeRunOptions) {
+
+}
+```
+
+This module could be grafted on to a subclass that gets generated at runtime and meets all the requirements 
+
+## CLI Internal Implementation idea 
+
+This is pseudocode, but will illustrate how I think we can accomplish the above.
+
+The CLI would just call the execute method with whatever container.argv is as its input (container.argv is the result of minimist)
+
+Any other kind of dispatcher that is using commands and wants to accept arbitrary subclasses can also use this execute method, and not have to worry about the simple command overriding the run method
+
+```ts
+type CommandOptions, CommandState etc ( zod schema inferred, make sure to follow feature, client, server implementations )
+
+class Command extends Helper<CommandOptions,CommandState,COmmandEvents> {
+    // private, but we should allow the CLI to reach in and call this ?
+    private async execute(params) {
+        return this.run(params)
+    }
+    
+    // NOTE: CommandRunOptions is not the same as the CommandOptions or HelperOptions passed to the constructor
+    // In fact the command options are more high level (e.g, is it running from the CLI? dispatched over RPC, an MCP call
+    // an agent tool? Commands are just atomic units of work that can be requested.
+    run(options: CommandRunOptions) {
+        // you don't need to super this ever, any subclass of command implements its own run
+        // SimpleCommands can export run and safely override this, because the CLI doesn't call run directly it calls execute
+    }
+}
+```
+
+
+
+
+
+

package/docs/examples/assistant/CORE.md

@@ -0,0 +1,18 @@
+# Luca Assistant Example
+
+You are currently an example / template "Assistant" provided by the Luca framework.  ( You'll probably have no idea what that is, don't worry, it doesn't matter ).
+
+You are what gets scaffolded when a user writes the `luca scaffold assistant` command.
+
+In luca, an Assistant is backed by a folder which has a few components:
+
+- CORE.md -- this is a markdown file that will get injected into the system prompt of a chat completion call
+- tools.ts -- this file is expected to export functions, and a schemas object whose keys are the names of the functions that get exported, and whose values are zod v4 schemas that describe the parameters
+- hooks.ts -- this file is expexted to export functions, whose names match the events emitted by the luca assistant helper
+
+Currently, the user is chatting with you from the `luca chat` CLI.  
+
+You should tell them what each of these files is and how to edit them.
+
+It is also important for them to know that the luca `container` is globally available for them in the context of the `tools.ts` and `hooks.ts` files.
+

package/docs/examples/assistant/hooks.ts

@@ -0,0 +1,3 @@
+export function started() {
+	console.log('Assistant started!')
+}

package/docs/examples/assistant/tools.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+export const schemas = {
+	README: z.object({}).describe('CALL THIS README FUNCTION AS EARLY AS POSSIBLE')
+}
+
+export function README(options: z.infer<typeof schemas.README>) {
+	return 'YO YO'
+}
+

package/docs/examples/window-manager-layouts.md

@@ -0,0 +1,180 @@
+---
+title: "Window Manager Layouts"
+tags: [windowManager, layout, native, ipc, macos, multi-window]
+lastTested: null
+lastTestPassed: null
+---
+
+# Window Manager Layouts
+
+Spawn and manage multiple windows at once using the layout API. Layouts let you declare groups of browser and terminal windows that open in parallel, or sequence multiple groups so each batch waits for the previous one to finish.
+
+## Overview
+
+The `windowManager` feature exposes two layout methods:
+
+- **`spawnLayout(config)`** — spawns all entries in parallel, returns `WindowHandle[]`
+- **`spawnLayouts(configs)`** — spawns multiple layouts sequentially (each layout's windows still spawn in parallel), returns `WindowHandle[][]`
+
+Each entry in a layout is a `LayoutEntry` — either a browser window or a TTY window. Type detection is automatic: if the entry has a `command` field or `type: 'tty'`, it's a terminal. Otherwise it's a browser window.
+
+## Setup
+
+```ts
+const wm = container.feature('windowManager', {
+  autoListen: true,
+  requestTimeoutMs: 10000
+})
+console.log('Window Manager ready')
+```
+
+## Single Layout — Parallel Windows
+
+Spawn a mix of browser and terminal windows that all open at the same time.
+
+```ts 
+const handles = await wm.spawnLayout([
+  { url: 'https://github.com', width: '50%', height: '100%', x: 0, y: 0 },
+  { url: 'https://soederpop.com', width: '50%', height: '100%', x: '50%', y: 0 },
+  { command: 'top', title: 'System Monitor', width: 900, height: 400, x: 0, y: 720 },
+])
+
+console.log('Spawned', handles.length, 'windows')
+handles.forEach((h, i) => console.log(`  [${i}] windowId: ${h.windowId}`))
+```
+
+All three windows open simultaneously. The returned `handles` array preserves the same order as the config entries, so `handles[0]` corresponds to the GitHub window, `handles[1]` to HN, and `handles[2]` to htop.
+
+## Percentage-Based Dimensions
+
+Dimensions (`width`, `height`, `x`, `y`) accept percentage strings resolved against the primary display. This makes layouts portable across different screen resolutions.
+
+```ts skip
+// Side-by-side: two windows each taking half the screen
+const handles = await wm.spawnLayout([
+  { url: 'https://github.com', width: '50%', height: '100%', x: '0%', y: '0%' },
+  { url: 'https://news.ycombinator.com', width: '50%', height: '100%', x: '50%', y: '0%' },
+])
+```
+
+You can mix absolute and percentage values freely:
+
+```ts skip
+const handles = await wm.spawnLayout([
+  { url: 'https://example.com', width: '75%', height: 600, x: '12.5%', y: 50 },
+  { command: 'htop', width: '100%', height: '30%', x: '0%', y: '70%' },
+])
+```
+
+## Explicit Type Field
+
+You can be explicit about entry types using the `type` field. This is equivalent to the implicit detection but more readable when mixing window types.
+
+```ts skip
+const handles = await wm.spawnLayout([
+  { type: 'window', url: 'https://example.com', width: 800, height: 600 },
+  { type: 'tty', command: 'tail -f /var/log/system.log', title: 'Logs' },
+])
+
+console.log('Browser window:', handles[0].windowId)
+console.log('TTY window:', handles[1].windowId)
+```
+
+## Sequential Layouts
+
+Use `spawnLayouts()` when you need windows to appear in stages. Each layout batch spawns in parallel, but the next batch waits until the previous one is fully ready.
+
+```ts skip
+const [dashboards, tools] = await wm.spawnLayouts([
+  // First batch: main content
+  [
+    { url: 'https://grafana.internal/d/api-latency', width: 960, height: 800, x: 0, y: 0 },
+    { url: 'https://grafana.internal/d/error-rate', width: 960, height: 800, x: 970, y: 0 },
+  ],
+  // Second batch: supporting tools (opens after dashboards are ready)
+  [
+    { command: 'htop', title: 'CPU', width: 640, height: 400, x: 0, y: 820 },
+    { command: 'tail -f /var/log/system.log', title: 'Logs', width: 640, height: 400, x: 650, y: 820 },
+  ],
+])
+
+console.log('Dashboards:', dashboards.map(h => h.windowId))
+console.log('Tools:', tools.map(h => h.windowId))
+```
+
+This is useful when the second batch depends on the first being visible — for example, positioning tool windows below dashboard windows.
+
+## Lifecycle Events on Layout Handles
+
+Every handle returned from a layout supports the same event API as a single `spawn()` call. You can listen for `close` and `terminalExited` events on each handle independently.
+
+```ts skip
+const handles = await wm.spawnLayout([
+  { url: 'https://example.com', width: 800, height: 600 },
+  { command: 'sleep 5 && echo done', title: 'Short Task' },
+])
+
+const [browser, terminal] = handles
+
+browser.on('close', () => console.log('Browser window closed'))
+
+terminal.on('terminalExited', (info) => {
+  console.log('Terminal process finished:', info)
+})
+```
+
+## Window Chrome Options
+
+Layout entries support all the same window chrome options as regular `spawn()` calls.
+
+```ts skip
+const handles = await wm.spawnLayout([
+  {
+    url: 'https://example.com',
+    width: 400,
+    height: 300,
+    alwaysOnTop: true,
+    window: {
+      decorations: 'hiddenTitleBar',
+      transparent: true,
+      shadow: true,
+      opacity: 0.9,
+    }
+  },
+  {
+    url: 'https://example.com/overlay',
+    width: 200,
+    height: 100,
+    window: {
+      decorations: 'none',
+      clickThrough: true,
+      transparent: true,
+    }
+  },
+])
+```
+
+## Operating on All Handles
+
+Since layouts return arrays of `WindowHandle`, you can easily batch operations across all windows.
+
+```ts skip
+const handles = await wm.spawnLayout([
+  { url: 'https://example.com/a', width: 600, height: 400 },
+  { url: 'https://example.com/b', width: 600, height: 400 },
+  { url: 'https://example.com/c', width: 600, height: 400 },
+])
+
+// Navigate all windows to the same URL
+await Promise.all(handles.map(h => h.navigate('https://example.com/updated')))
+
+// Screenshot all windows
+await Promise.all(handles.map((h, i) => h.screengrab(`./layout-${i}.png`)))
+
+// Close all windows
+await Promise.all(handles.map(h => h.close()))
+```
+
+## Summary
+
+The layout API builds on top of `spawn()` and `spawnTTY()` to orchestrate multi-window setups. Use `spawnLayout()` for a single batch of parallel windows, and `spawnLayouts()` when you need staged sequences. Every returned handle supports the full `WindowHandle` API — events, navigation, eval, screenshots, and more.

package/docs/in-memory-fs.md

@@ -0,0 +1,4 @@
+# In Memory FS
+
+If we rigorously ensured all file system operations of other features, servers, clients, etc 
+went through the container.fs system, we could very easily build in memory file systems