# Foundry > Documentation for Foundry's local developer tools. ## Marbles - [Marbles](https://francois-esquire.github.io/foundry/marbles): Write local automations in TypeScript and run them with a standalone CLI. ### Get Started - [Installation](https://francois-esquire.github.io/foundry/marbles/get-started/installation): Install the standalone Marbles CLI and prepare your own project. - [Your first automation](https://francois-esquire.github.io/foundry/marbles/get-started/quickstart): Write a small TypeScript automation, inspect its output, and change it. - [Using Marbles](https://francois-esquire.github.io/foundry/marbles/get-started/using-marbles): Explore the capabilities you can combine in a local automation. ### Foundation - [The Marbles model](https://francois-esquire.github.io/foundry/marbles/foundation/api): Understand the relationship between an automation, its steps, and each run. - [Definitions and instances](https://francois-esquire.github.io/foundry/marbles/foundation/definitions-and-instances): Separate declaring work, placing it in a workflow, and executing a run. - [Steps and workflow composition](https://francois-esquire.github.io/foundry/marbles/foundation/composition): Connect typed results into a tree that executes in dependency order. - [Execution contexts](https://francois-esquire.github.io/foundry/marbles/foundation/contexts): Understand what each callback receives and how resources become part of a run. - [Workspaces and sandboxes](https://francois-esquire.github.io/foundry/marbles/foundation/workspaces-and-sandboxes): Choose where files, commands, agents, and isolated environments operate. - [Agents and sessions](https://francois-esquire.github.io/foundry/marbles/foundation/agents-and-sessions): Add model work to a step, understand its bindings, and keep a conversation when needed. - [Artifacts and results](https://francois-esquire.github.io/foundry/marbles/foundation/artifacts-and-results): Distinguish step results, readable reports, and versioned outputs that survive a run. - [Durability](https://francois-esquire.github.io/foundry/marbles/foundation/durability): How Marbles records work, owns agent execution, retries failures, and resumes parked runs. - [Schedules and monitors](https://francois-esquire.github.io/foundry/marbles/foundation/triggers): Run work on a clock or react when a file or HTTP source changes. - [Local execution and state](https://francois-esquire.github.io/foundry/marbles/foundation/execution-and-state): Connect the automation lifecycle to CLI processes and the stores they keep on disk. - [Foundry primitives](https://francois-esquire.github.io/foundry/marbles/foundation/primitives): The libraries Marbles combines into one local automation runtime. ### Use Cases #### Software Factory - [Software Factory](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory): Understand the roles, records, and loops behind development, maintenance, and improvement. ##### Development - [Take an issue](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/intake): Choose a ready issue and define what a successful change must prove. - [Keep a work log](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/work-log): Use one artifact per issue to retain intent, evidence, decisions, and handoffs. - [Plan the work](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/plan): Record an implementation approach against the issue and its starting revision. - [Implement the issue](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/implement): Create the candidate branch and preserve the first implementation and every revision. - [Test and review](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/verify): Check a candidate against the original issue, plan, implementation, and previous findings. - [Revise the candidate](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/revise): Carry findings into another attempt without losing the issue history. - [Approve and deliver](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/development/approve): Approve the exact reviewed commit, publish its pull request, and track completion. ##### Maintenance - [Review existing pull requests](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/maintenance/pull-requests): Dispatch focused reviewers with shared context and synthesize findings before requesting changes. - [Run an on-call shift](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/maintenance/on-call): Investigate incidents, name an owner, and leave evidence for the next shift. - [Watch repository and dependency changes](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/maintenance/signals): Turn repository drift and upstream releases into evidence for new issues. - [Schedule updates and reports](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/maintenance/automate): Fetch remote changes, report tracked work, and keep on-call attention visible. ##### Improvement - [Inspect the factory](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/improvement/inspector): Check whether code maintenance, agents, and skills are producing useful results. - [Improve code maintainability](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/improvement/maintainability): Turn an observed maintenance cost into a scoped code change with evidence before and after. - [Improve agents, prompts, and skills](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/improvement/agents-and-skills): Diagnose a recurring agent failure and propose a versioned change to the instructions or setup. - [Evaluate a proposed improvement](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/improvement/evaluate): Compare the candidate with the current factory and check whether it fixes the observed weakness. - [Adopt changes and track results](https://francois-esquire.github.io/foundry/marbles/use-cases/software-factory/improvement/adopt): Approve a specific improvement, retain the previous version, and check whether it helps in practice. #### Evaluations - [Evaluations](https://francois-esquire.github.io/foundry/marbles/use-cases/evaluations): Compare models, harnesses, and skills against recorded tasks and explicit checks. - [Compare models and harnesses](https://francois-esquire.github.io/foundry/marbles/use-cases/evaluations/compare): Make controlled comparisons and keep failures, uncertainty, and operating cost visible. - [Test and improve skills](https://francois-esquire.github.io/foundry/marbles/use-cases/evaluations/skills): Compare skill instructions against concrete cases and review proposed improvements before adopting them. - [Run checks when files change](https://francois-esquire.github.io/foundry/marbles/use-cases/evaluations/watch): Launch an evaluation from a skill edit and keep the feedback loop bounded. #### Design - [Design](https://francois-esquire.github.io/foundry/marbles/use-cases/design): Carry a product brief through wireframes, design iterations, implementation, and ongoing care. - [Brief and wireframes](https://francois-esquire.github.io/foundry/marbles/use-cases/design/wireframes): Establish the product task and information order before refining the visual design. - [Adjust the design](https://francois-esquire.github.io/foundry/marbles/use-cases/design/iterate): Use explicit design variables and evidence to guide each iteration. - [Build and review](https://francois-esquire.github.io/foundry/marbles/use-cases/design/deliver): Turn an approved design into an implementation with explicit visual and interaction evidence. - [Keep tokens in sync](https://francois-esquire.github.io/foundry/marbles/use-cases/design/sync): Check a Figma library on a schedule and propose its color palette as a pull request. #### Productivity - [Productivity](https://francois-esquire.github.io/foundry/marbles/use-cases/productivity): Build a morning briefing from the work your team did while you were away. - [Connect your sources](https://francois-esquire.github.io/foundry/marbles/use-cases/productivity/prerequisites): Prepare Google Docs, Slack, and GitHub access in the CLI that will collect your briefing. - [Build the morning report](https://francois-esquire.github.io/foundry/marbles/use-cases/productivity/morning-report): Record your departure, collect a fixed window of updates, and save a briefing with evidence. - [Have it ready each morning](https://francois-esquire.github.io/foundry/marbles/use-cases/productivity/schedule): Schedule the briefing locally, recover missed mornings, and choose how to read it. ### Reference - [CLI reference](https://francois-esquire.github.io/foundry/marbles/reference/cli): Commands, flags, and dashboard keys for running and inspecting Marbles. - [MCP server](https://francois-esquire.github.io/foundry/marbles/reference/mcp): Launch workflows and agents over STDIO, then watch their output by run ID. - [API reference](https://francois-esquire.github.io/foundry/marbles/reference/api): Authoring factories, builders, resource operations, context properties, and triggers. - [Agent sessions](https://francois-esquire.github.io/foundry/marbles/reference/agent-sessions): Host and sandbox options, permissions, questions, child agents, and managed triggers. - [Project structure and environment](https://francois-esquire.github.io/foundry/marbles/reference/project): Folder discovery, ignored files, workspace roots, setup, names, and module resolution. - [State](https://francois-esquire.github.io/foundry/marbles/reference/state): Disk layout, recovery of parked runs, locks, and the limits of continuity. - [Safety and limits](https://francois-esquire.github.io/foundry/marbles/reference/safety): What dry execution substitutes and what your code can still do. - [Troubleshooting](https://francois-esquire.github.io/foundry/marbles/reference/troubleshooting): Diagnose installation, discovery, input, scheduling, agent, and state problems. - [Remote execution](https://francois-esquire.github.io/foundry/marbles/reference/remote): Run the CLI on another host and understand the current deployment boundary. - [Embedding the engine](https://francois-esquire.github.io/foundry/marbles/reference/engine): Host Marbles in a Bun application with explicit dependencies and lifecycle ownership. ### Roadmap - [Roadmap](https://francois-esquire.github.io/foundry/marbles/roadmap): What Marbles is focused on now, what comes next, and where it is heading. ## Prompts - [Prompts](https://francois-esquire.github.io/foundry/prompts): Write prompts for Claude Code, Codex, and Pi, and know what they reference. - [Editor support](https://francois-esquire.github.io/foundry/prompts/editor): A VS Code extension that highlights what a prompt references, in TypeScript and in skill files. - [Linting](https://francois-esquire.github.io/foundry/prompts/lint): ESLint, Oxlint, and Biome rules that check what a prompt references, as you write it. ## Spyglass - [Spyglass](https://francois-esquire.github.io/foundry/spyglass): A map of a codebase, generated from the code and served locally. - [Start Here](https://francois-esquire.github.io/foundry/spyglass/start-here): Install Spyglass, scan a workspace, and open the viewer. - [Examples](https://francois-esquire.github.io/foundry/spyglass/examples): Explore Spyglass's map of the Foundry repository. ### Concepts - [How Spyglass reads a codebase](https://francois-esquire.github.io/foundry/spyglass/concepts/how-spyglass-reads-a-codebase): The ways a scan understands a workspace, and where each result lands. ### Guides - [Scan a workspace](https://francois-esquire.github.io/foundry/spyglass/guides/scan-a-workspace): What a scan reads, what it writes, how it stays incremental, and what to do when it fails. - [Explore the map](https://francois-esquire.github.io/foundry/spyglass/guides/explore-the-map): What the map shows, how to move around it, and what selecting a place reveals. - [History](https://francois-esquire.github.io/foundry/spyglass/guides/history): Add Git checkpoints to a scan and see how the workspace changed. ### Reference - [CLI](https://francois-esquire.github.io/foundry/spyglass/reference/cli): Commands, flags, output, and exit codes of the spyglass binary. - [Library](https://francois-esquire.github.io/foundry/spyglass/reference/library): scan and serve from code, what they return, their errors, and the types @foundry.sh/spyglass exports. - [Configuration](https://francois-esquire.github.io/foundry/spyglass/reference/configuration): The configuration directory, .foundry/spyglass/, its settings, domains, and rules, and what else Spyglass reads from a workspace. - [Output](https://francois-esquire.github.io/foundry/spyglass/reference/output): The dataset a scan writes, file by file. ## Agent resources - [llms-full.txt](https://francois-esquire.github.io/foundry/llms-full.txt): The full Markdown of every page in one file. - [Page Markdown](https://francois-esquire.github.io/foundry/index.md): Append `.md` to any page URL to fetch that page as raw Markdown. - [JSON API](https://francois-esquire.github.io/foundry/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://francois-esquire.github.io/foundry/openapi.json. - [API catalog](https://francois-esquire.github.io/foundry/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here. - [agent-readability.json](https://francois-esquire.github.io/foundry/agent-readability.json): Manifest of every agent-facing artifact on this site. - [Sitemap](https://francois-esquire.github.io/foundry/sitemap.xml): Every indexable page URL with its last-modified date.