# Granary > Give your agent better context. ## Start here - [Introduction](/getting-started/introduction.md): Granary brings the docs and source a coding agent needs into the repository where it works. An API reference tells an agent what a method accepts. Source explains what it actually does. Examples show how to use it. A context pack keeps that material together, with an entry file that tells the agent where to start. ## Packs - [Prebuilt packs](/packs.md): Choose a recommended language set or install focused standards packs individually. - [Recommended](/packs/recommended.md): Install a language pack together with engineering, Git, documentation, and agent instructions. - [Recommended TypeScript](/packs/recommended/typescript.md): Install functional TypeScript and the four shared standards packs together. - [Recommended Rust](/packs/recommended/rust.md): Install functional Rust and the four shared standards packs together. - [Recommended Python](/packs/recommended/python.md): Install functional Python and the four shared standards packs together. - [Languages](/packs/languages.md): Language-specific rules for functional code, explicit failures, and behavioral testing. - [TypeScript](/packs/languages/typescript.md): Write functional TypeScript with declared functions, immutable values, typed Results, and exhaustive matching. Covers module layout, naming, types, state, composition, JSDoc, and behavioral tests. - [Conditionals](/packs/languages/typescript/conditionals.md): Exit invalid paths with guards and handle closed variants through exhaustive matching. - [Errors](/packs/languages/typescript/errors.md): Carry failure as a typed Result, contain third-party exceptions, and classify failures without text matching. - [File structure](/packs/languages/typescript/file-structure.md): Assign modules to their owning capability and keep package entrypoints deliberate and shallow. - [Functional TypeScript](/packs/languages/typescript/README.md): Use immutable values, declared functions, factories, typed Results, and exhaustive matching. Apply this pack to TypeScript source and examples. - [Functions](/packs/languages/typescript/functions.md): Make operations findable with declarations, explicit contracts, named inputs, and a single responsibility. - [JSDoc](/packs/languages/typescript/comments.md): Explain call-site behavior in multiline JSDoc, demonstrate public usage, and identify private declarations. - [Naming](/packs/languages/typescript/naming.md): Name concrete operations and domain values, with casing that stays predictable across platforms. - [Paradigm](/packs/languages/typescript/paradigm.md): Build behavior from immutable functions, inject resources through factories, and isolate effects in adapters. - [State](/packs/languages/typescript/state.md): Produce new values for state changes and keep mutable resource handles separate from installation data. - [Testing](/packs/languages/typescript/testing.md): Prove observable contracts with real local files and processes, reserving test doubles for external services. - [Types](/packs/languages/typescript/types.md): Validate external values, retain readonly contracts, and represent source variants with discriminated unions. - [Utilities](/packs/languages/typescript/utilities.md): Use the existing utility vocabulary and make pipeline stages and I/O concurrency explicit. - [Rust](/packs/languages/rust.md): Use ownership and borrowing to keep domain logic pure. Covers native Result and Option, exhaustive enums, iterator composition, crate layout, API contracts, and behavioral tests. - [Comments](/packs/languages/rust/comments.md): Document Rust public contracts, failure cases, and borrow requirements with verifiable examples. - [Conditionals](/packs/languages/rust/conditionals.md): Use early guards for rejection and exhaustive matches for Rust domain variants. - [Errors](/packs/languages/rust/errors.md): Return typed Rust Results and propagate expected failures without panics or unchecked extraction. - [File structure](/packs/languages/rust/file-structure.md): Organize Rust modules by owning capability and keep public crate exports deliberate. - [Functional Rust](/packs/languages/rust/README.md): Use pure functions, native Results, exhaustive enums, borrowed inputs, and iterator transformations. Apply this pack to Rust source and examples. Read bytefarm/engineering through the installation index first. Repository commands, the supported compiler, and dependency approval come from the consumer's operating instructions. Identity: bytefarm/rust-functional. Content version: 0.1.0. - [Functions](/packs/languages/rust/functions.md): Declare focused Rust operations with explicit input ownership and return contracts. - [Naming](/packs/languages/rust/naming.md): Use Rust casing conventions and name concrete operations and domain values. - [Ownership](/packs/languages/rust/ownership.md): Borrow inputs, produce new domain values, and avoid clones or interior mutation that hide ownership. - [Paradigm](/packs/languages/rust/paradigm.md): Compose native Rust functions and immutable values while isolating resource effects. - [Testing](/packs/languages/rust/testing.md): Verify Rust value contracts, resource adapters, and public examples with real observable outcomes. - [Types](/packs/languages/rust/types.md): Use enums, newtypes, and validated boundaries to represent valid Rust domain states. - [Utilities](/packs/languages/rust/utilities.md): Use native Rust iterator and Result combinators before adding an extension crate. - [Python](/packs/languages/python.md): Build Python around pure transformations, immutable domain values, explicit capabilities, and typed Results with returns. Covers modules, types, state, composition, documentation, and behavioral tests. - [Comments](/packs/languages/python/comments.md): Document Python caller-facing constraints, typed failure variants, and resource effects. - [Conditionals](/packs/languages/python/conditionals.md): Use early Python guards and explicit variant handling without exception-driven branching. - [Errors](/packs/languages/python/errors.md): Return typed Python failures and adapt external exceptions without authored raise or try/except. - [File structure](/packs/languages/python/file-structure.md): Keep Python domain modules independent of presentation, runtime wiring, and resource adapters. - [Functional Python](/packs/languages/python/README.md): Use pure functions, immutable domain values, explicit capabilities, and typed Results. Never author raise or try/except application control flow. Apply this pack to Python source and examples. Read bytefarm/engineering through the installation index first. Use returns for typed failure and composition; its documented decorator/composition typing requires the compatible mypy plugin. A recommendation is not dependency installation authorization. Identity: bytefarm/python-functional. Content version: 0.1.0. - [Functions](/packs/languages/python/functions.md): Declare focused typed Python operations with named inputs and explicit failure contracts. - [Naming](/packs/languages/python/naming.md): Use native Python casing and name concrete domain operations and values. - [Paradigm](/packs/languages/python/paradigm.md): Compose pure Python functions and immutable domain values with explicit effect boundaries. - [State](/packs/languages/python/state.md): Produce new Python domain values and prevent mutation hidden inside frozen records. - [Testing](/packs/languages/python/testing.md): Verify typed Python outcomes, real resource boundaries, and the supported returns typing setup. - [Types](/packs/languages/python/types.md): Validate external Python values and model immutable domain alternatives with explicit typed contracts. - [Utilities](/packs/languages/python/utilities.md): Use returns for typed composition and native Python iterators for straightforward transformations. - [Shared standards](/packs/shared.md): Language-independent rules for engineering decisions, review, documentation, and agent context. - [Engineering](/packs/shared/engineering.md): Keep domain logic pure and effects behind resource-owning adapters. Covers focused changes, immutable state, errors as values, dependency evaluation, meaningful comments, and behavioral testing. - [Change discipline](/packs/shared/engineering/change-discipline.md): Tie each edited line to an observable outcome and preserve unrelated behavior. - [Code comments](/packs/shared/engineering/comments.md): Explain hidden constraints and required ordering without restating the surrounding code. - [Dependencies](/packs/shared/engineering/dependencies.md): Evaluate capability, typing, maintenance, and licensing before expanding the dependency vocabulary. - [Errors as values](/packs/shared/engineering/errors-as-values.md): Represent expected failures as typed outcomes and contain external exception behavior at adapters. - [Functional design](/packs/shared/engineering/functional-design.md): Compose pure transformations and isolate effects behind explicit resource capabilities. - [Functional engineering](/packs/shared/engineering/README.md): Shared rules for pure domain logic, immutable values, explicit failures, and resource-owning adapters. Apply these principles alongside the pack for the language being edited. Identity: bytefarm/engineering. Content version: 0.1.0. - [Immutability](/packs/shared/engineering/immutability.md): Return new domain values and keep mutable resource handles separate from application state. - [Testing](/packs/shared/engineering/testing.md): Test consequential decisions and real boundaries with observable success and failure contracts. - [Git](/packs/shared/git.md): Make each change understandable in history and review. Covers scoped commits, useful commit messages, focused pull requests, and accurate verification evidence. - [Commits](/packs/shared/git/commits.md): Describe one scoped change and preserve the consumer repository’s history and release rules. - [Git standards](/packs/shared/git/README.md): Keep history and review scoped to an explainable change. Identity: bytefarm/git. Content version: 0.1.0. Authorization, branch protection, release workflows, and repository tooling are defined by the consuming repository. - [Pull requests](/packs/shared/git/pull-requests.md): Keep reviews scoped, verification evidence accurate, and follow-up discussion continuous. - [Documentation](/packs/shared/documentation.md): Choose a page shape from the reader's task. Covers writing, portable Markdown, diagrams, standards, guides, quick starts, tutorials, references, troubleshooting, and runbooks. - [Diagrams](/packs/shared/documentation/diagrams.md): Show one relationship clearly using a small Mermaid diagram or a text tree for file layout. - [Documentation standards](/packs/shared/documentation/README.md): Choose a page shape from the reader's task. Keep its contracts accurate when copied into a local context pack. Identity: bytefarm/documentation. Content version: 0.1.0. Language-specific API comments belong to the selected language component. - [Formatting](/packs/shared/documentation/formatting.md): Keep Markdown portable across copied packs, with concise metadata and examples readers can execute. - [Guides](/packs/shared/documentation/guides.md): Document a task with prerequisites, ordered actions, an observable result, and fixes for known failures. - [Quick starts](/packs/shared/documentation/quickstarts.md): Take a new reader to one working result in at most five steps, with executable commands and clear output. - [References](/packs/shared/documentation/references.md): Describe caller-facing contracts precisely: inputs, defaults, outputs, failures, limits, and valid examples. - [Runbooks](/packs/shared/documentation/runbooks.md): Make repeatable operating procedures verifiable at each step, with explicit rollback and escalation paths. - [Standards authoring](/packs/shared/documentation/standards.md): Write normative rules with reasons, focused examples, and an honest account of automated and manual enforcement. - [Troubleshooting](/packs/shared/documentation/troubleshooting.md): Organize failures by recognizable symptoms, give a bounded fix, and show how to verify recovery. - [Tutorials](/packs/shared/documentation/tutorials.md): Teach through a bounded build: each step changes something the reader can inspect and explains one concept. - [Writing](/packs/shared/documentation/writing.md): Assign every page a reader task and keep contributor rules separate from product explanation. - [Agent instructions](/packs/shared/agent-instructions.md): Give coding agents a short operating contract and a route to the right context. Covers repository instructions, canonical rule ownership, and reading order across installed packs. - [Agent instruction standards](/packs/shared/agent-instructions/README.md): Give agents a short operating contract and a map to the canonical rules for their current task. Identity: bytefarm/agent-instructions. Content version: 0.1.0. - [Agent instructions](/packs/shared/agent-instructions/instructions.md): Keep operating instructions short and route detailed rules to canonical reference material. - [Context routing](/packs/shared/agent-instructions/context-routing.md): Read selected preset components in order and apply each language’s rules only to its own files. ## Guides - [Create a context pack](/guides/create-pack.md): Author a reusable pack around existing reference material, then validate and adopt it. Use granary init instead to set up a consuming project at its root. ## Reference - [CLI](/reference/cli.md): The granary-ai npm package installs granary. It supports local/Git sources, locked restoration, reviewed updates, and standards conversion. Requires Node.js 26+ and Git; macOS and Linux are supported. ## Others - [Concepts](/concepts.md) - [Clients and plugins](/concepts/client-plugins.md): Expose a small factory-based client that works without plugins. Prebuilt interpretation plugins are optional and compose through the same contracts as third-party plugins. The granary-ai package exposes factories that return clients directly; operations return Granary-owned plain typed outcomes. See the API reference for complete contracts. - [Granary context packs](/concepts/context-packs.md): Your project uses a particular version of a tool. A coding agent may know a different version, and your team's conventions may not exist in its training data at all. Links and pasted excerpts help for one conversation; the next agent starts without them. Granary copies the docs, source, and examples you choose into your repository and links their entrypoints directly in AGENTS.md. Install a selection from a local directory or Git repository; the agent reads it with its existing search tools. The lock records which upstream commits and bytes you installed, so teammates can restore the same material. - [Installation model](/concepts/installation.md): Granary installs selected reference material into consumer-owned paths, defaulting to .granary/context/. - [Manifest and pack installation proposal](/concepts/manifest-api-proposal.md): Status: draft for review. This describes a proposed API, not the currently implemented schema. Approval covers the design; it does not authorize publishing or dependency changes. Granary distributes source material that consumers own. A pack can contain docs, code, examples, standards, and other packs. One granary.json describes a project that provides material, consumes material, or does both. - [Pack maintenance and skills](/concepts/pack-maintenance.md): Treat installed reference material as content a project may intentionally customize, with explicit review when upstream changes arrive. Implemented: retained baselines, read-only three-way previews, reviewed update application, durable accepted customizations, customized restoration, and shipped maintenance skills. Later unaccepted edits remain protected. - [Skills compatibility](/concepts/skills-compatibility.md): Granary borrows skills' source-based installation experience while defining a separate reference-material contract. - [Standards documents](/concepts/standards-documents.md): Represent standards as readable Markdown with extractable structure, including their rationale, rules, examples, and enforcement. Implemented: explicit document kinds, marxml-backed validation, complete JSON/Markdown extraction, a Greptile Markdown exporter, and review-default consumer enforcement. Executable transforms remain deferred. - [Composable standards packs](/concepts/standards-packs.md): Split the engineering reference into independent packs, then select a recommended set for each language. Each component directory under packs/ owns its granary.json. packs/granary.json composes the distributed sets. The root manifest installs only the five shared/TypeScript components; Rust and Python remain distribution material. - [Contributing](/contributing.md): Before editing Granary, identify the behavior you intend to change and read the rules for that part of the CLI or library. - [Agent context](/contributing/agents.md): Start a repository task at root AGENTS.md. It owns commands and permission boundaries and links directly to installed standards. Granary declares only bytefarm/recommended-typescript in its own dependencies. The installed set contains engineering, Git, documentation, agent instructions, and functional TypeScript. Read the component entrypoints in that order, then the topics needed by the change. Almanac's standards region indexes installed shared/TypeScript pages. Its contributor/public region indexes repository workflow and product references. Authored Rust and Python material remains in packs/ for distribution and example verification. Edit authored component pages, then follow the deliberate refresh procedure in Contributing. Installed files and their lock are generated outputs. A normal install verifies and restores the recorded resolution. See using agent context for consumer guidance and project configuration for destination and integrity contracts. - [Getting started](/getting-started.md) - [Install your first framework context](/getting-started/quick-start.md): Install Next.js 16 documentation into a disposable project without choosing upstream files or cloning Granary. - [Guides](/guides.md) - [Install context packs](/guides/install-packs.md): Install selected reference material from local directories or Git repositories. - [Use a pack with your agent](/guides/use-agent-context.md): Granary links installed reference files directly in root AGENTS.md so your agent can find them on demand. - [Use Granary maintenance skills](/guides/use-granary-skills.md): Install the skill directories shipped with granary-ai so your coding agent can follow pack authoring and maintenance procedures. These skills are for authored reusable packs, including local packs and curated pack definitions. They are not general workflows for arbitrary installed context, a framework docs recipe, or copied application code. A consumer packs entry, lock entry, or .granary/context/ directory alone does not establish an authored pack. Confirm its source definition before using maintenance skills. Ordinary context keeps the CLI's restoration, review, and edit-protection behavior without requiring these skills. - [Reference](/reference.md) - [Client and core API](/reference/core-api.md): granary-ai combines SDK exports, optional plugin subpaths, and the granary executable. Importing its root never starts the CLI. The workspace separates @granary/core, @granary/sdk, @granary/cli, and @granary/plugins; these component packages remain private and have not been independently published. - [Separate upstream sources](/reference/pack-definition.md): A curated granary.json composes selected material from other repositories. It uses the same manifest contract as a portable pack or consumer project; there is no separate definition format. The curated pack catalog in the repository's packs/README.md lists independently installable definitions for Next.js, React, TanStack Query, Router, Start, Hono, Zod, and Vercel AI SDK. Each is an ordinary packs//granary.json selecting official documentation and attribution at an exact upstream commit. These snapshots do not automatically match installed dependency versions and are separate from the language standards sets. The checked-in docs/examples/react/granary.json selects React documentation and implementation from independent sources: Each member owns its source, exact revision, selection, and destination. Selection retains source-relative paths, so docs appear beneath docs/src/content/ and code beneath code/packages/react/src/. No package-version lookup or implicit Git tag derivation occurs. - [Pack manifest](/reference/pack-manifest.md): An installable pack's granary.json describes files and included packs. Only name is required; the same contract configures consumer projects through the granary-ai CLI and SDK. The workflows are separate: granary init sets up context consumption at a project root; granary create authors a reusable definition around reference material. Pack creation does not install that material or register it in a consuming project. See create a context pack. - [Presets](/reference/presets.md): A recommended set is a pack containing other packs. Membership is recursive and explicit; directory discovery does not imply inclusion. Installing this pack includes both members and their declared members. Its own files are omitted unless files is supplied. Child destinations are namespaced beneath the selected parent destination. Cycles and conflicting destinations fail before writes. See project configuration. - [Project configuration](/reference/project-config.md): granary.json describes authored packs and adopted source material. Only name is required. Put source-backed selections and named inline definitions under packs. The granary-ai CLI and SDK use the same contract. The upstream repository does not need a manifest. Selected code, docs, examples, and binary files are copied as consumer-owned material, not executed or installed as dependencies. - [Sources](/reference/sources.md): Local directories and Git repositories supply reference material. Sources can own a granary.json, but participation is optional: consumers can select ordinary repository files themselves. Revisions belong in manifest values as shorthand strings or explicit branch, tag, or commit selectors. An omitted selector uses the remote default branch. A locator's # suffix selects a pack, not a revision.