# Auggy

> Auggy is a small Bun and TypeScript runtime for building self-hosted agents from composable augments.

The kernel runs model turns and validated tools. Augments add memory, context, transports, skills, policy, integrations, and other capabilities around those turns. Start with a working agent and install only what it needs.

This file is an index for coding agents and search/answer agents. Every curated docs page below links to its markdown version. The same set in one file is at https://auggy.dev/llms-full.txt.

## Key Docs

### Start

- [1. Run an agent](https://auggy.dev/docs/quickstart/markdown): Published. Create a local Auggy agent and complete the first model turn.
- [2. Add an augment](https://auggy.dev/docs/add-augment/markdown): Published. Install layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.
- [3. Build an augment](https://auggy.dev/docs/build-augment/markdown): Published. Build one project-specific typed tool inside a custom augment.
- [4. Deploy and verify](https://auggy.dev/docs/deploy/markdown): Published. Deploy the agent to Railway and verify its health, route, console, and application client.

### Runtime

- [How Auggy works](https://auggy.dev/docs/architecture/markdown): Published. How Auggy's small turn kernel and composable augments form a self-hosted agent runtime.
- [Tools](https://auggy.dev/docs/add-tools/markdown): Published. Expose typed actions the model can select during a turn and your code executes.
- [Skills](https://auggy.dev/docs/add-skills/markdown): Published. Teach the model when and how to use an augment without loading every instruction into context on every turn.
- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown): Published. Use memory for persistent peer and agent context, and knowledge for read-only reference sources.
- [Model providers](https://auggy.dev/docs/engines/markdown): Published. Configure the model provider Auggy's kernel calls each turn.
- [Transports](https://auggy.dev/docs/transports/markdown): Published. Expose the agent over web chat, AG-UI, Telegram, and other inbound surfaces.
- [Connect MCP servers](https://auggy.dev/docs/mcp/markdown): Published. Bridge local or remote MCP server tools into Auggy with deploy-aware policy.

### Augments

- [Browse all augments](https://auggy.dev/docs/augments/markdown): Published. Understand how built-in and custom augments add capabilities to an Auggy agent.

### Operate

- [Console](https://auggy.dev/docs/console/markdown): Published. Test the running agent and inspect its capabilities, caller contexts, tool calls, and live runtime configuration.
- [Logs and recovery](https://auggy.dev/docs/logs-and-recovery/markdown): Published. Use Auggy and Railway diagnostics to recover from deploy, boot, route, and runtime failures.
- [Security](https://auggy.dev/docs/security/markdown): Published. Auggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.

### Advanced Preview

- [Optional app integration](https://auggy.dev/docs/engineering-patterns/markdown): Preview. Advanced preview routes, generated clients, webhooks, and delegated authorization for agents that need a small deterministic application boundary.

### Reference

- [CLI reference](https://auggy.dev/docs/cli-reference/markdown): Published. Common Auggy CLI commands for creating, extending, and operating agents.
- [agent.yaml](https://auggy.dev/docs/agent-yaml/markdown): Published. Configure identity, engine, and enabled augment order for an agent project.
- [defineAugment](https://auggy.dev/docs/define-augment/markdown): Published. Define a runtime capability that contributes tools, context, memory, transports, lifecycle, or policy to an agent.
- [defineTool](https://auggy.dev/docs/define-tool/markdown): Published. Define a typed model-callable function with validation and optional authorization requirements.
- [Changelog](https://auggy.dev/docs/changelog/markdown): Published. Latest published runtime and CLI updates.

## Machine-Readable API

- https://auggy.dev/api-reference.json: exported symbols, route options, config files, CLI commands, and the generated-client contract, each with signatures and a release status.

## Feature Status

- Published: Turn kernel, custom augments, typed tools, skills, web transport, Console, and Railway deploy. Available in the latest npm baseline (0.5.0).
- Published: Memory, knowledge, MCP, AgentMail, Telegram, visitor recognition, and notifications. Available in the npm 0.5.0 baseline, including AgentMail inbound, reply/forward, durable recovery, outbound review, and Svix verification.
- Preview: Augment HTTP routes, route manifests, OpenAPI export, generated clients, webhooks, and delegated app authorization. Usable optional app-integration surfaces, but not part of the default project or primary product promise.
- Preview: bash, budgets, link. Implemented enough to experiment with, but intentionally behind explicit setup or confirmation.

## Current Product Shape

- Runtime: Bun and TypeScript.
- Package: auggy on npm.
- Core project file: agent.yaml is the runtime source of truth for an agent project.
- Identity file: identity.md is stable operator-authored identity and policy context.
- Skills: skills/ contains trust-filtered teaching files. The model receives a compact manifest and reads a matching SKILL.md on demand before answering in that domain.
- Knowledge: knowledge/ contains read-only reference sources installed by the knowledge augment.
- State: data/ contains durable augment and runtime state such as SQLite files.
- Secrets: .env or provider-owned systems, not prompt-visible docs.
- Trust levels today: creator, agent, and public.

## Stable Built-In Augments

- fileMemory: loads identity.md and creator-approved agent-global learned-behaviors.md into context. Default learned writes require a runtime-verified creator and explicit PERSISTED confirmation.
- filesystem: gives the agent scoped file access.
- webTransport: serves chat, console, health, home, and AG-UI turn endpoints.
- webFetch: lets the agent fetch URLs and HTTP APIs.
- turnControl: lets the agent pause and ask for clarification.
- knowledge: installs local markdown and API-backed knowledge sources.
- layeredMemory: stable opt-in peer memory backed by SQLite. Explicit writes use memory_write({ topic, content }); CLI installs keep automatic extraction off by default, and cross-session continuity requires a stable recognized peer identity.
- visitorAuth: provides visitor magic-link sign-in.
- notify: sends outbound notifications to an operator or service.
- agentMail: 0.5.0 provides policy-gated send, reply, and forward tools; polling/WebSocket/Svix inbound; durable catch-up and recovery; and creator-reviewed outbound actions.
- telegramTransport: supports bidirectional Telegram chat.
- mcp: connects local or remote MCP servers.

## Advanced Preview App Integration

Custom augments may optionally expose focused deterministic HTTP routes for a frontend, webhook, or server integration. This is an advanced preview surface, not a requirement for a normal Auggy project and not a replacement for an application's primary backend.

- Use a route when software already knows the exact operation it needs.
- Use a tool when the model should mediate the operation during a turn.
- Routes and tools do not need to duplicate each other.

The preview includes augment routes, route groups, schemas, response helpers, body caps, timeouts, rate limits, route manifests, OpenAPI export, generated TypeScript clients, visitor tokens, external auth assertions, webhook policy metadata, Stripe and Svix signature verification, and delegated authorization.

## Auth And Authorization

- Runtime authentication and authorization are deterministic transport/runtime decisions.
- The model does not decide who is authorized.
- Apps using Clerk, Supabase Auth, Auth0-style middleware, or custom sessions can mint short-lived Auggy auth assertions with explicit scopes and grants.
- Auggy enforces route and tool access from those assertions.

## Docs Authority

Use this order when Auggy docs appear to disagree:

1. Public docs pages and their status labels describe the supported surface.
2. Feature Status distinguishes Published and Preview behavior.
3. Examples and guides should be treated as implementation patterns only when they match the current status labels.
4. Preview pages describe usable surfaces that may change before 1.0.

## Status Notes

- Latest published release: 0.5.0.
- Auggy is turn-oriented today; it is not a durable workflow engine or persistent job queue.
- Pin exact versions for production work until 1.0.0.

## Page Summaries

## Auggy

URL: https://auggy.dev/docs/overview/markdown
Status: Published
Summary: Build self-hosted agents from a small turn runtime and composable augments.
Sections: A small runtime for self-hosted agents, Build one complete agent, The runtime in one minute, Choose the right abstraction

# Auggy

Canonical: https://auggy.dev/docs
Status: Published
Package: auggy 0.5.0

Build self-hosted agents from a small turn runtime and composable augments.

## A small runtime for self-hosted agents

**Auggy** is a **Bun** and TypeScript runtime for building self-hosted agents. The kernel runs model turns; augments add tools, memory, context, transports, skills, policy, and integrations around those turns.

**One turn**

```
inbound message
  -> transport identifies the peer
  -> augments contribute context and memory
  -> kernel calls the configured model
  -> model requests typed tools when needed
  -> kernel validates and executes tool calls
  -> transport returns the result
```

Agent projects remain ordinary files and TypeScript. Start with a working local agent, install only the capabilities it needs, and keep your frontend, database, auth provider, job system, and existing services in their current stack.

## Build one complete agent

| Step | Outcome |
| --- | --- |
| [1. Run an agent](https://auggy.dev/docs/quickstart/markdown) | Create a local agent, connect a model provider, and complete the first turn. |
| [2. Add an augment](https://auggy.dev/docs/add-augment/markdown) | Install peer-scoped memory and verify it without writing runtime code. |
| [3. Build an augment](https://auggy.dev/docs/build-augment/markdown) | Give the agent one project-specific typed tool. |
| [4. Deploy and verify](https://auggy.dev/docs/deploy/markdown) | Ship the agent runtime and verify its production health and logs. |

## The runtime in one minute

| Part | Job |
| --- | --- |
| Agent | A portable project with identity, model configuration, skills, and enabled augments. |
| Kernel | Runs model turns, tool execution, context, history, and runtime policy. |
| Augment | Adds a coherent runtime capability without changing the kernel. |
| Tool | A typed function the model can request during a turn. |
| Skill | Optional workflow guidance read when tool descriptions are not enough. |
| Knowledge | Reference material fetched only when it is relevant. |

## Choose the right abstraction

| Choose | Use it when | Examples |
| --- | --- | --- |
| Skill or knowledge | The agent needs teaching or reference material, not new runtime behavior. | Playbooks, examples, policies, product facts, and FAQs. |
| Built-in augment | A supported optional capability already fits the job. | Memory, knowledge, MCP, Telegram, notifications, or visitor recognition. |
| Custom augment | The agent needs a new typed tool, integration, context source, policy, lifecycle hook, or transport. | Project-specific support lookup, reporting, escalation, or service integration. |

> **Note: Current operational boundary**
>
> **Auggy** is turn-oriented today. Keep durable jobs, resumable workflows, artifact pipelines, and authenticated approval records in application infrastructure until the runtime provides explicit primitives for them. Optional augment routes and delegated app authorization are available as advanced preview integrations.

## Related

- [Run an agent](https://auggy.dev/docs/quickstart/markdown)
- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)
## Run an agent

URL: https://auggy.dev/docs/quickstart/markdown
Status: Published
Summary: Create a local Auggy agent and complete the first model turn.
Sections: Before you start, Create an agent, Add the provider credential, Start the runtime, Verify the first turn, What just started, Next: add a capability

# Run an agent

Canonical: https://auggy.dev/docs/quickstart
Status: Published
Package: auggy 0.5.0

Create a local **Auggy** agent and complete the first model turn.

## Before you start

- Node.js 20 or newer for the npm package.
- **Bun** 1.2 or newer for the generated agent project.
- An API key for a hosted model provider, or a running Ollama instance.

## Create an agent

**Install and scaffold**

```bash
npm i -g auggy
auggy create my-agent
cd my-agent
```

The create flow asks for the agent name, purpose, provider, and model, then writes a runnable **Bun** project.

## Add the provider credential

Open .env and set the variable named in .env.example. Provider keys belong in .env, never in agent.yaml, skills, memory, or application code.

**.env example for Anthropic**

```env
ANTHROPIC_API_KEY=sk-ant-...
```

## Start the runtime

**Validate and run**

```bash
auggy doctor
auggy run
```

doctor validates the project and provider configuration. run starts the runtime and opens creator chat.

**Run output**

```
Agent "my-agent" is live.

  Chat:     http://localhost:8080/console/chat
  Console:  http://localhost:8080/console
  Health:   http://localhost:8080/health
  Home:     http://localhost:8080/
```

## Verify the first turn

1. Open the printed Chat URL and send: Who are you, and what can you do?
2. Confirm the reply reflects the name and purpose selected during create.
3. If the turn fails, read the foreground terminal, correct the reported provider or configuration error, and rerun `auggy doctor`.

## What just started

| Part | What it did |
| --- | --- |
| Runtime kernel | Loaded the project and completed the model turn. |
| Model provider | Resolved the configured adapter and model client. |
| Web transport | Served chat, console, health, and the agent runtime endpoint. |
| Console | Provided the local creator surface for chat and runtime inspection. |

## Next: add a capability

| Continue | Outcome |
| --- | --- |
| [Add an augment](https://auggy.dev/docs/add-augment/markdown) | Install peer-scoped memory and see how an augment extends the running agent. |

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Model provider](https://auggy.dev/docs/engines/markdown)
- [agent.yaml](https://auggy.dev/docs/agent-yaml/markdown)
## Add an augment

URL: https://auggy.dev/docs/add-augment/markdown
Status: Published
Summary: Install layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.
Sections: Add memory without runtime code, Install layeredMemory, Inspect the installed files, Validate and boot, Verify memory in Console, Know what the skill adds, Go deeper or build your own

# Add an augment

Canonical: https://auggy.dev/docs/add-augment
Status: Published
Package: auggy 0.5.0

Install layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.

## Add memory without runtime code

This guide adds the stable layeredMemory augment to the agent from the previous step. It gives the agent peer-scoped SQLite memory, model-callable memory tools, recent-memory context, and bundled guidance without asking you to write TypeScript.

**What changes**

```
Conversation
  -> memory_write({ topic, content })
  -> data/memory.db
  -> recent memory on a later turn for the same peer
```

## Install layeredMemory

**Run from the agent project**

```bash
cd my-agent
auggy augment add layeredMemory
```

The command enables the augment in agent.yaml, writes project-owned configuration, and copies its bundled skill. layeredMemory has no additional npm package or environment-variable requirement.

## Inspect the installed files

**Relevant project changes**

```
my-agent/
  agent.yaml                         # lists layeredMemory in boot order
  augments/
    README.md
    layeredMemory/
      augment.yaml                   # project-owned config
  skills/
    layeredMemory/
      SKILL.md                       # installed guidance snapshot
  data/
    memory.db                        # created when the runtime boots
```

**augments/layeredMemory/augment.yaml**

```yaml
type: layeredMemory
config:
  backend: sqlite
  dbPath: ./data/memory.db
  namespace: my-agent
  retentionDays: 90
  autoSave:
    enabled: false
```

> **Note: Config here, implementation in the package**
>
> Built-in runtime source remains inspectable under `node_modules`/auggy/src. The local augment folder contains configuration so package updates can deliver runtime and security fixes without replacing project-owned settings.

## Validate and boot

**Restart with the new augment**

```bash
auggy doctor
auggy run
```

doctor checks the project before startup. The runtime initializes the SQLite store on boot, so data/memory.db appears after run starts rather than during augment add.

## Verify memory in Console

1. Open `/console/chat` and keep the caller set to Creator. Creator has the stable peer ID creator, which makes this local check repeatable.
2. Send: Remember that I prefer concise replies.
3. Expand the `memory_write` tool call. Confirm it used a topic such as preferences and returned `PERSISTED`.
4. Start a new chat as Creator and ask: What response style do I prefer? Recent peer memory should supply the preference; the agent can use `memory_search` for a targeted lookup.

| Result | Meaning |
| --- | --- |
| `PERSISTED` | The selected provider confirmed the write. |
| `NOT_PERSISTED` | Nothing was saved; inspect the tool result and runtime logs. |
| `PERSISTENCE_UNKNOWN` | The provider failed after the final state became uncertain; inspect before retrying. |

> **Warning: A repeat visitor needs stable identity**
>
> Cross-session visitor recall requires visitorAuth or an application-auth assertion that resolves the same recognized peer. Anonymous identities are session-scoped by default.

## Know what the skill adds

| Layer | Responsibility |
| --- | --- |
| Tool schema and description | Expose `memory_search`, `memory_write`, `memory_list`, and `memory_forget` and explain their immediate purpose. |
| Bundled skill | Teach what is worth saving, peer scoping, privacy boundaries, retrieval strategy, and persistence-result handling. |
| Runtime | Derive the current peer, enforce authorization, isolate stored entries, and inject recent memory. |

**Refresh the bundled skill later**

```bash
auggy skill add layeredMemory
```

Refresh overwrites the installed layeredMemory skill snapshot. Keep project-specific teaching in a separate user-authored skill.

## Go deeper or build your own

| Next | Use it for |
| --- | --- |
| [Augments](https://auggy.dev/docs/augments/markdown) | Understand composition, ownership, and the built-in catalog. |
| [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown) | Choose memory destinations and identity requirements. |
| [Skills](https://auggy.dev/docs/add-skills/markdown) | Learn when model guidance belongs in a skill. |
| [Console](https://auggy.dev/docs/console/markdown) | Inspect caller identity, capabilities, and tool results. |
| [Build an augment](https://auggy.dev/docs/build-augment/markdown) | Author a project-specific typed capability in TypeScript. |

## Related

- [Augments](https://auggy.dev/docs/augments/markdown)
- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
## Build an augment

URL: https://auggy.dev/docs/build-augment/markdown
Status: Published
Summary: Build one project-specific typed tool inside a custom augment.
Sections: What you will build, Create the augment, Where it lives, Write the integration, Keep the boundary explicit, Add a tool, Install and verify the tool, Before you add more

# Build an augment

Canonical: https://auggy.dev/docs/build-augment
Status: Published
Package: auggy 0.5.0

Build one project-specific typed tool inside a custom augment.

## What you will build

A support augment with one `search_cases` tool. During conversation, the agent uses it when a customer describes a problem without knowing the exact case ID or database query.

**One focused capability**

```
Customer message
  -> kernel -> model -> search_cases
  -> validated query -> support system
  -> structured result -> model response
```

> **Note: Keep the first augment small**
>
> The model handles vague intent. Typed project code performs the lookup. You do not need an HTTP route, generated client, or delegated app authorization to build a useful **Auggy** agent.

## Create the augment

Run this inside the agent project created in the previous guide.

**Scaffold a custom augment**

```bash
auggy augment create support
```

## Where it lives

**Recommended file tree**

```
my-agent/
  augments/
    support/
      augment.yaml
      index.ts
      cases.ts
      support.test.ts
```

The generated index.ts can hold a small capability. Move support-system access into cases.ts so it remains easy to test without a model turn.

> **Note: Add a skill when the description is not enough**
>
> A single-purpose tool usually needs only a clear description. When the model also needs sequencing, examples, or recovery guidance, add skills/support/SKILL.md.

## Write the integration

**augments/support/cases.ts**

```ts
export interface SupportCase {
  id: string;
  summary: string;
  status: "open" | "closed";
}

export async function searchCases(query: string): Promise<SupportCase[]> {
  // Replace with your existing support API or database adapter.
  return [
    {
      id: "case_1042",
      summary: `Delivery address correction matching: ${query}`,
      status: "open",
    },
  ];
}
```

## Keep the boundary explicit

| Layer | Responsibility |
| --- | --- |
| Tool description | Tells the model when the lookup is useful. |
| Zod input | Rejects missing or malformed model-provided arguments. |
| Integration function | Calls the support system and returns exact data. |
| Runtime policy | Controls which callers may see or invoke the tool. |

## Add a tool

The tool lets the model turn a customer's description into one validated support lookup. Its description is enough for this straightforward operation, so the augment does not need a skill yet.

**augments/support/index.ts**

```ts
import { defineAugment, defineTool } from "auggy";
import { z } from "zod";
import { searchCases } from "./cases";

const SearchCases = z.object({
  query: z.string().trim().min(1),
});

export default function supportAugment() {
  return defineAugment({
    name: "support",
    type: "custom",
    tools: [
      defineTool({
        name: "search_cases",
        description: "Find support cases relevant to a vague customer request.",
        category: "support",
        input: SearchCases,
        execute: async ({ query }) =>
          JSON.stringify({ cases: await searchCases(query) }),
      }),
    ],
  });
}
```

## Install and verify the tool

**Test, install, and run**

```bash
auggy augment test ./augments/support
auggy augment install my-agent ./augments/support
auggy doctor
auggy run
```

1. Open `/console/chat` and ask: Find the case about changing my delivery address.
2. Expand the `search_cases` tool call and confirm its query was validated.
3. Confirm the result includes `case_1042` and the final response does not invent another case.
4. Run the augment test again after replacing the example integration with your support-system adapter.

## Before you add more

| If the capability needs | Add |
| --- | --- |
| Non-obvious sequencing, examples, or recovery | [A skill](https://auggy.dev/docs/add-skills/markdown) |
| Peer-scoped history across turns | [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown) |
| Tools from an existing MCP server | [MCP](https://auggy.dev/docs/mcp/markdown) |
| A direct frontend or webhook entry point | [Advanced preview routes](https://auggy.dev/docs/add-http-routes/markdown) |

> **Warning: A tool is not automatically safe**
>
> Use trust policy, authorization, narrow schemas, and integration-level checks before exposing customer records or consequential actions. Model instructions are not an enforcement boundary.

## Related

- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)
## Deploy and verify

URL: https://auggy.dev/docs/deploy/markdown
Status: Published
Summary: Deploy the agent to Railway and verify its health, route, console, and application client.
Sections: Before you deploy, First deploy, Verify the production path, Persistent state

# Deploy and verify

Canonical: https://auggy.dev/docs/deploy
Status: Published
Package: auggy 0.5.0

Deploy the agent to **Railway** and verify its health, route, console, and application client.

## Before you deploy

- Install the **Railway** CLI and run railway login.
- Run from the agent project, not the application repository.
- Keep webTransport on port 8080 for the generated **Railway** container.
- Commit application source normally, but keep the agent's .env out of Git.

## First deploy

**Validate and deploy**

```bash
cd my-agent
auggy doctor
auggy deploy
```

1. Choose or create the **Railway** workspace, project, and service.
2. Review the redacted environment-variable diff.
3. Confirm deployment; **Auggy** stages the agent without local-only files and syncs secrets.
4. **Auggy** mounts persistent data at /app/data, assigns a domain, and deploys the service.
5. The command verifies /health and records the deployment in .auggy-cloud.json.

## Verify the production path

**Health, route, and logs**

```bash
curl "https://<agent-domain>/health"
curl "https://<agent-domain>/services?need=gift&maxBudgetUsd=200"
auggy logs
```

1. Confirm /health returns a successful response.
2. Confirm the deployed /services route returns the same result as local development.
3. Open the deployed `/console/integrations` with creator credentials and inspect route and auth state.
4. Set NEXT_PUBLIC_AUGGY_BASE_URL in the application deployment to the agent domain and redeploy the application.
5. Run the service search from the production application.

## Persistent state

**Railway** mounts a volume at /app/data. Startup verifies that exact advertised mount and proves atomic write/fsync/rename durability before stateful augments boot. Core SQLite paths resolve directly onto the volume; they do not depend on root-level symlinks.

| Path | Augment |
| --- | --- |
| /app/data/memory.db | layeredMemory |
| /app/data/budgets.db | budgets |
| /app/data/visitor-auth.db | visitorAuth |
| /app/data/link.db | link |
| /app/data/agent-mail/<augment-name>/agent-mail.db | AgentMail, isolated per augment instance |

> **Warning: Fail closed on ephemeral storage**
>
> **Railway** startup refuses a missing, differently mounted, or symlinked runtime root. Do not add /app/*.db compatibility symlinks for new state; only Link retains its legacy symlink.

> **Note: The tutorial catalog is stateless**
>
> The catalog example does not require a volume. Persistent storage matters when you add memory, visitor authentication, budgets, or other SQLite-backed augments.

## Related

- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
- [Logs and recovery](https://auggy.dev/docs/logs-and-recovery/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
## Architecture

URL: https://auggy.dev/docs/architecture/markdown
Status: Published
Summary: How Auggy's small turn kernel and composable augments form a self-hosted agent runtime.
Sections: System shape, Runtime kernel, What augments contribute, Turn execution, Inside one turn, What is not in the kernel

# Architecture

Canonical: https://auggy.dev/docs/architecture
Status: Published
Package: auggy 0.5.0

How **Auggy**'s small turn kernel and composable augments form a self-hosted agent runtime.

## System shape

| Layer | Owns |
| --- | --- |
| Kernel | Turn execution, context allocation, model calls, validated tool execution, history, and turn results. |
| Augments | Tools, memory, context, skills, transports, policy, lifecycle hooks, and integrations. |
| Your systems | Frontend, database, auth provider, payments, durable jobs, approvals, and external APIs. |

The kernel stays small. Augments connect it to the systems your application already uses.

## Runtime kernel

| Kernel part | Responsibility |
| --- | --- |
| Turn loop | Orchestrates a single model turn end to end. |
| Context allocator | Assembles history, context blocks, and tool definitions within a token budget. |
| Capability table | Tracks exposed tools, blocked tools, trust rules, and tool-call counters. |
| History manager | Maintains thread history and keeps `tool_use`/`tool_result` pairs coherent. |
| Tool selector | Filters tools through capability policy before the engine sees them. |
| Lifecycle manager | Boots augments, runs shutdown hooks, and reports health. |
| Transport admission | Rate-limits and bounds concurrent inbound turns per transport. |
| Trace records | Capture context, tool, inference, cost, timing, and validation events in each TurnResult. |

> **Note: Runtime data is not the same as console UI**
>
> TurnResult records more than the current console renders. See Console for the UI available today.

## What augments contribute

| Contribution | What it provides |
| --- | --- |
| Tools | Typed actions the model can select during a conversation. |
| Skills and context | On-demand guidance and scoped prompt context. |
| Memory | Durable state providers and retrieval tools. |
| Transports | Inbound channels such as web chat, AG-UI, and Telegram. |
| Lifecycle and policy | Boot validation, migrations, cleanup, auth requirements, rates, budgets, and operator controls. |

An augment can provide one or several of these. Group behavior by capability, not by individual function.

## Turn execution

**Normal runtime path**

```
User message
  -> transport
  -> kernel assembles context and tools
  -> model requests a tool
  -> runtime validates and executes it
  -> transport returns the result
```

> **Note: Optional app integration is separate**
>
> Advanced preview augment routes can serve an existing frontend or webhook without a model turn. They are not required for a normal agent and do not turn **Auggy** into a general web framework.

## Inside one turn

1. Admission: Resolve caller trust, queue, rate, and budget checks.
2. Assembly: Build context from history, hooks, memory, and tool schemas.
3. Inference: Call the configured model provider.
4. Execution: Validate and authorize selected tools, then append their results.
5. Finalization: Validate output, compact history, record trace data, and run end hooks.

Inference and tool execution may repeat until the model finishes or maxInferenceLoops is reached. Tool results stay paired with their tool calls in thread history.

## What is not in the kernel

- No planner component. The model plans by choosing tools.
- No retrieval engine. Retrieval belongs in memory or knowledge augments.
- No general web framework. Keep the application's normal API in its existing stack.
- No durable workflow engine or persistent job queue. Keep long-running orchestration in a workflow system or application service.
- No automatic policy inheritance. Each capability declares and enforces its own trust and operational limits.

## Related

- [Security](https://auggy.dev/docs/security/markdown)
## Add tools

URL: https://auggy.dev/docs/add-tools/markdown
Status: Published
Summary: Expose typed actions the model can select during a turn and your code executes.
Sections: When to add a tool, Tool shape, Tool policy

# Add tools

Canonical: https://auggy.dev/docs/add-tools
Status: Published
Package: auggy 0.5.0

Expose typed actions the model can select during a turn and your code executes.

## When to add a tool

- The agent needs to retrieve, create, update, or send something during conversation.
- The operation needs typed input and code-enforced execution.
- The model can decide when the operation is useful, but should not hand-write the side effect.
- A route alone would force the visitor into a rigid form before intent is clear.

## Tool shape

**Tool with Zod input**

```ts
import { defineTool } from "auggy";
import { z } from "zod";

export const lookupOrder = defineTool({
  name: "lookup_order",
  description: "Look up an order after the visitor is verified.",
  category: "commerce",
  input: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => {
    const order = await getOrder(orderId);
    return JSON.stringify({ order });
  },
});
```

## Tool policy

- Put narrow, explicit descriptions on tools; the model uses them to decide whether to call.
- Use Zod input schemas to constrain model-provided input before execution.
- Use delegated requires rules for protected tools when app-owned authorization matters.
- Return structured strings, usually JSON, so the next model step can reason from exact output.
- Move business logic into domain functions so routes and tools can share it.

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [defineTool](https://auggy.dev/docs/define-tool/markdown)
## Skills

URL: https://auggy.dev/docs/add-skills/markdown
Status: Published
Summary: Teach the model when and how to use an augment without loading every instruction into context on every turn.
Sections: What skills are, Tool description or skill?, What belongs where, Folder convention, When to include one, Refresh bundled guidance

# Skills

Canonical: https://auggy.dev/docs/add-skills
Status: Published
Package: auggy 0.5.0

Teach the model when and how to use an augment without loading every instruction into context on every turn.

## What skills are

Skills are markdown files the model reads on demand through the filesystem augment. Every turn receives a compact, trust-filtered manifest with each matching skill's exact SKILL.md path. The runtime instructs the model to read a relevant skill before answering or using tools in that domain, without loading every skill body into every turn.

Trust filtering applies to discovery and filesystem access. Creator-only skills are absent from public manifests, and public read, list, or search requests cannot reach them through alternate path spellings or symlink aliases.

| Layer | What loads | Cost |
| --- | --- | --- |
| Manifest | Name and description for each mounted skill. | Small idle context. |
| SKILL.md body | Full teaching file read with `fs_read` when relevant. | Only when needed in a thread. |
| References | Detailed supporting files under references/. | Only when the model requests depth. |

## Tool description or skill?

Start with the tool description. Add a skill only when the model needs a larger operating playbook than the tool definition can express clearly.

| Mechanism | Use it for |
| --- | --- |
| Tool description | Helping the model select one tool and understand its immediate purpose. |
| Skill | Optional workflow guidance: sequencing, clarification, judgment, failure recovery, and coordination across tools. |
| Runtime code | Enforcing schemas, authorization, consent, business invariants, and consequential state changes. |

**The description handles selection**

```ts
defineTool({
  name: "save_lead",
  description: "Save a qualified lead for creator follow-up.",
  input: CreateLeadSchema,
  execute: async (input) => JSON.stringify(await saveLead(input)),
});
```

**The skill handles the workflow**

```
# Lead intake

- Ask for an email address and a concrete need.
- Ask one clarifying question when qualification is incomplete.
- Save the lead before notifying the operator.
- If saving fails, do not claim the lead was recorded.
- Escalate only when urgency or purchase intent meets the documented criteria.
```

> **Warning: Skills do not enforce policy**
>
> Put authorization, consent requirements, validation, and business invariants in runtime code. A skill can guide model behavior, but it is not a security boundary.

## What belongs where

| Primitive | Role |
| --- | --- |
| Augment | Runtime capability mounted at boot. |
| Tool | Callable function exposed to the model. |
| Skill | Optional markdown playbook the model reads when a workflow needs more guidance. |

A skill provides no tools, routes, or lifecycle hooks. If the capability needs code, it belongs in an augment; if the model needs judgment about that code, it belongs in the skill.

## Folder convention

**Skill folder**

```
skills/
  memory/
    SKILL.md
    references/
      provider-types.md
  filesystem/
    SKILL.md
    references/
      mount-permissions.md
  escalation/
    SKILL.md
```

**SKILL.md frontmatter**

```
---
name: memory
description: When/how to use memory_read, memory_write, memory_search, memory_list, memory_forget
---

# Memory Tools

Teach when to use each tool, common mistakes, and workflows.
```

## When to include one

- Include a skill when tools have non-obvious interaction patterns.
- Include a skill when there are judgment calls, do-not rules, or multi-step workflows.
- Skip a skill when the tool name and description are enough.
- If you would brief a teammate for more than 30 seconds before using the capability, add a skill.

## Refresh bundled guidance

**Refresh an existing project**

```bash
auggy skill add auggy
auggy skill add layeredMemory
```

The first command refreshes the general **Auggy** build-out guide. The second refreshes the peer-memory teaching for an installed layeredMemory augment. Bundled refreshes overwrite that skill folder's installed snapshot, so keep project-specific teaching in a separate user-authored skill.

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
## Memory and knowledge

URL: https://auggy.dev/docs/memory-and-knowledge/markdown
Status: Published
Summary: Use memory for persistent peer and agent context, and knowledge for read-only reference sources.
Sections: Difference, Setup, Choose the write destination, Safety

# Memory and knowledge

Canonical: https://auggy.dev/docs/memory-and-knowledge
Status: Published
Package: auggy 0.5.0

Use memory for persistent peer and agent context, and knowledge for read-only reference sources.

## Difference

| Surface | Use it for |
| --- | --- |
| fileMemory | Static identity and creator-approved, agent-global learned behavior. |
| layeredMemory | Stable opt-in peer-scoped episodic memory backed by SQLite. |
| knowledge | Read-only local markdown and API-backed reference sources. |
| skills | Instructional markdown that teaches the model when/how to use tools. |

## Setup

**Common memory and knowledge augments**

```bash
auggy augment add knowledge
auggy augment add layeredMemory
```

CLI installs enable explicit topic-based memory writes immediately and leave automatic extraction off by default. Auto-save requires an explicit extraction-engine configuration and adds model-call cost.

**knowledge layout**

```
knowledge/
  sources.json
  local/
    manifest
    mission.md
    context.md
```

## Choose the write destination

| Intent | Write | Authority |
| --- | --- | --- |
| Change agent-global operating behavior | `memory_write` with label: learned | Runtime-verified creator only by default |
| Remember a fact about the current person | `memory_write` with a topic | Writable peer memory such as layeredMemory |

- Visitor facts never belong in learned-behaviors.md.
- Cross-session peer recall requires durable storage and a stable recognized identity from visitor auth or an external app-auth assertion.
- Say a write was saved only after `memory_write` returns `PERSISTED`.
- `NOT_PERSISTED` means it was not saved. `PERSISTENCE_UNKNOWN` means the provider failed after the final state became uncertain; do not retry blindly.

## Safety

- Keep operator-authored identity in identity.md, not in learned peer memory.
- Do not store secrets in memory, skills, or knowledge files.
- Use peer-scoped memory for visitor facts; do not promote peer-derived facts to system truth without operator control.
- Use knowledge for reference content that should be read but not mutated by the model.

## Related

- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)
## Model provider

URL: https://auggy.dev/docs/engines/markdown
Status: Published
Summary: Configure the model provider Auggy's kernel calls each turn.
Sections: What it configures, Provider families, Minimal configuration, Model-provider fields, Provider-specific configuration, Resolution and validation, Common failures, Cost and limits

# Model provider

Canonical: https://auggy.dev/docs/engines
Status: Published
Package: auggy 0.5.0

Configure the model provider **Auggy**'s kernel calls each turn.

## What it configures

Every turn, the kernel calls one configured model provider. The configuration resolves the provider adapter, the model, token limits, and provider-specific options such as routing and cost metadata.

> **Note: Why the config key is engine**
>
> The config resolves a provider adapter package and a model client, not just a model id, then exposes one model-client interface to the kernel. That resolved unit is the engine.

## Provider families

### Anthropic

**Hosted Claude models.** Use the native Anthropic adapter for hosted Claude development and production turns.

Credential: `ANTHROPIC_API_KEY`

```yaml
engine:
  provider: anthropic
  model: claude-sonnet-4-6
```

### OpenAI

**Hosted OpenAI models.** Use the OpenAI adapter with the same kernel and typed-tool contract.

Credential: `OPENAI_API_KEY`

```yaml
engine:
  provider: openai
  model: gpt-5.4-mini
```

### OpenRouter

**Routed model access.** Use OpenRouter when the selected model should run through its provider-routing service.

Credential: `OPENROUTER_API_KEY`

```yaml
engine:
  provider: openrouter
  model: anthropic/claude-sonnet-4-6
```

### Ollama

**Local or remote models.** Use a local Ollama runtime for development and private experiments, or configure a remote compatible host.

Credential: `No key required locally`

```yaml
engine:
  provider: ollama
  model: llama3.2
```

## Minimal configuration

Choose the provider during `auggy create`. After scaffolding, agent.yaml is the source of truth for the provider and model while .env supplies hosted provider credentials.

**agent.yaml**

```yaml
engine:
  provider: anthropic
  model: claude-sonnet-4-6
  maxContextTokens: 200000
  maxTokens: 4096
```

**Hosted provider key**

```env
ANTHROPIC_API_KEY=sk-ant-...
```

## Model-provider fields

| Field | Applies to | Use |
| --- | --- | --- |
| provider | All providers | Required. One of anthropic, openai, openrouter, or ollama. |
| model | All providers | Required. Provider-specific model identifier. |
| maxContextTokens | All providers | Maximum context window **Auggy** should plan around. |
| maxTokens | All providers | Maximum output tokens per turn; OpenAI and OpenRouter receive it as `max_completion_tokens`. |
| baseURL | Anthropic, OpenAI, Ollama | Optional proxy, gateway, or remote Ollama base URL. OpenRouter is hardcoded to OpenRouter. |
| reasoningEffort | OpenAI, OpenRouter | Optional reasoning setting: none, minimal, low, medium, high, or xhigh. Unsupported models may reject it upstream. |
| providerRouting | OpenRouter only | Provider allow/deny, sort, and `max_price` routing hints forwarded to OpenRouter. |
| costOverride | Hosted pricing/cost estimation | Override USD-per-million-token rates for unknown models or custom pricing. |
| keepAlive | Ollama only | How long Ollama keeps the model loaded after a request. |
| options | Ollama only | Native Ollama generation options such as temperature, `top_k`, `top_p`, seed, `repeat_penalty`, or mirostat. |

> **Warning: No API keys in YAML**
>
> Provider API keys stay in .env or provider-owned secret stores. agent.yaml selects the provider and model; it does not store ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, or OLLAMA_API_KEY.

## Provider-specific configuration

**OpenRouter routing**

```yaml
engine:
  provider: openrouter
  model: anthropic/claude-sonnet-4-6
  maxContextTokens: 200000
  maxTokens: 4096
  reasoningEffort: medium
  providerRouting:
    only: [Anthropic]
    ignore: [SomeProvider]
    sort: price
    max_price:
      prompt: 3
      completion: 15
```

**Ollama local options**

```yaml
engine:
  provider: ollama
  model: llama3.2
  baseURL: http://localhost:11434
  maxContextTokens: 8192
  maxTokens: 1024
  keepAlive: 5m
  options:
    temperature: 0.2
    top_p: 0.9
    seed: 42
```

## Resolution and validation

1. agent.yaml: Selects the provider, model, token limits, and provider-specific options.
2. .env: Supplies the credential required by the selected hosted provider.
3. CLI: Validates field shapes and rejects provider-specific options on incompatible providers.
4. Runtime: Loads the provider adapter and exposes one model-client interface to the kernel.
5. Provider: Performs final model-name and option validation when a request is made.

Run `auggy doctor` after changing engine configuration. It catches local configuration and credential problems; a provider can still reject an unknown model or unsupported option at request time.

## Common failures

| Symptom | Check |
| --- | --- |
| Missing credential | Set the key for the selected provider in .env and restart the runtime. |
| Unknown model | Use a model identifier accepted by that provider; model availability changes independently of **Auggy**. |
| Context overflow | Set maxContextTokens to the real model window and keep maxTokens within provider limits. |
| Rejected reasoning option | Remove reasoningEffort or choose a model that supports the requested setting. |
| OpenRouter routing failure | Check provider names, allow/deny lists, and `max_price` values. |
| Ollama connection failure | Start Ollama, confirm baseURL, and verify the model is installed. |

## Cost and limits

- Hosted model providers bill through their provider or routing service.
- maxContextTokens guides context allocation; maxTokens limits requested output. Neither is a provider billing cap.
- Memory extraction can use model calls in addition to user-facing turns when enabled.
- Use the budgets augment as a runtime guardrail, but keep provider-side billing alerts and quotas in place.
- Pin exact **Auggy** versions and model choices for production work until 1.0.0.

## Related

- [Run an agent](https://auggy.dev/docs/quickstart/markdown)
- [agent.yaml](https://auggy.dev/docs/agent-yaml/markdown)
## Transports

URL: https://auggy.dev/docs/transports/markdown
Status: Published
Summary: Expose the agent over web chat, AG-UI, Telegram, and other inbound surfaces.
Sections: Web transport, Telegram

# Transports

Canonical: https://auggy.dev/docs/transports
Status: Published
Package: auggy 0.5.0

Expose the agent over web chat, AG-UI, Telegram, and other inbound surfaces.

## Web transport

A transport is the inbound surface that identifies the peer and creates the turn. Trust starts here: whoever the transport says is calling determines what the turn may do.

- Serves /agent/run, the AG-UI SSE runtime surface.
- Serves `/console` and `/console/chat` for creator-facing chat.
- Serves /health and the default home page.
- Owns visitor token and external auth assertion verification when configured.

## Telegram

telegramTransport provides bidirectional chat from Telegram. Add it when the agent should participate in Telegram conversations with runtime identity mapping and transport-specific configuration.

**Add Telegram transport**

```bash
auggy augment add telegramTransport
```

## Related

- [Console](https://auggy.dev/docs/console/markdown)
- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## MCP

URL: https://auggy.dev/docs/mcp/markdown
Status: Published
Summary: Bridge local or remote MCP server tools into Auggy with deploy-aware policy.
Sections: Purpose, Deploy safely

# MCP

Canonical: https://auggy.dev/docs/mcp
Status: Published
Package: auggy 0.5.0

Bridge local or remote MCP server tools into **Auggy** with deploy-aware policy.

## Purpose

The MCP augment imports tools from Model Context Protocol servers and applies **Auggy**'s trust and deployment rules.

**Add MCP**

```bash
auggy augment add mcp
```

## Deploy safely

- Remote MCP servers should use HTTPS in cloud deployments.
- Enabled stdio MCP servers fail cloud preflight unless marked cloud disabled or localOnly.
- Use allow/block lists and per-server/per-tool trust policy for broad MCP servers.

## Related

- [Architecture](https://auggy.dev/docs/architecture/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## Augments

URL: https://auggy.dev/docs/augments/markdown
Status: Published
Summary: Understand how built-in and custom augments add capabilities to an Auggy agent.
Sections: One runtime module, What an augment can contribute, Built-in and custom ownership, Choose an augment, Choose the next path

# Augments

Canonical: https://auggy.dev/docs/augments
Status: Published
Package: auggy 0.5.0

Understand how built-in and custom augments add capabilities to an **Auggy** agent.

## One runtime module

An augment is a runtime module that adds a coherent capability to an agent. It can contribute one surface, such as a transport, or keep related tools, context, memory, policy, storage, and operator controls together.

**Composition model**

```
Auggy kernel
  + webTransport       -> chat, console, health
  + layeredMemory      -> peer memory, tools, context
  + your support       -> typed tools, integration code
```

> **Note: Add or build**
>
> Add installs and configures an existing built-in. Build creates a custom augment whose TypeScript belongs to your project.

## What an augment can contribute

| Surface | Purpose |
| --- | --- |
| Tools | Typed operations the model can choose during a turn. |
| Context and memory | Turn context, durable providers, and retrieval or write behavior. |
| Lifecycle | Boot, shutdown, turn, idle, and background-work hooks. |
| Transports | Inbound and outbound channels such as web chat or Telegram. |
| Policy and operations | Tool constraints, health, admin information, and operator actions. |

A capability does not need every surface. Keep the augment as small as the operation requires, and add a skill only when tool descriptions are not enough to guide model behavior.

## Built-in and custom ownership

| Kind | Project owns | Implementation |
| --- | --- | --- |
| Built-in | agent.yaml entry, augment.yaml config, and an installed skill snapshot when provided | Installed auggy package under `node_modules`/auggy/src |
| Custom | augment.yaml, local TypeScript, tests, and optional source skill | augments/<name>/ in the agent project |

agent.yaml lists enabled augment IDs in boot order. Built-in config lives in augments/<id>/augment.yaml. Skills are copied into skills/<id>/ so the project can inspect and adapt its installed guidance.

## Choose an augment

### Core runtime

The compact chat-ready set installed by ``auggy create``. Each piece has a narrow runtime responsibility.

- [File Memory](https://auggy.dev/docs/augment-file-memory/markdown) — Core. Load identity and creator-approved global behavior from files. (`memory`, `context`)
- [Filesystem](https://auggy.dev/docs/augment-filesystem/markdown) — Core. Give the agent named, operator-controlled file mounts and a durable workspace. (`tools`, `context`)
- [Web Transport](https://auggy.dev/docs/augment-web-transport/markdown) — Core. Serve AG-UI turns, Console, health checks, and runtime discovery. (`transport`, `console`, `health`)
- [Web Fetch](https://auggy.dev/docs/augment-web-fetch/markdown) — Core. Fetch public URLs and return readable HTML text or JSON to the model. (`tool`)
- [Turn Control](https://auggy.dev/docs/augment-turn-control/markdown) — Core. Let the agent stop a turn and ask one answerable question. (`tool`, `turn status`)

### Memory and knowledge

Add durable per-person facts or controlled access to operator-maintained information.

- [Layered Memory](https://auggy.dev/docs/augment-layered-memory/markdown) — Stable. Persist peer-scoped episodic memory in SQLite with search, write, list, and forget tools, explicit write outcomes, and stable-identity requirements. (`memory`, `tools`, `context`)
- [Knowledge](https://auggy.dev/docs/augment-knowledge/markdown) — Stable. Expose listed local documents and remote knowledge endpoints on demand. (`tool`, `context`)

### Integrations

Connect the runtime to external tool providers and communication channels.

- [MCP](https://auggy.dev/docs/augment-mcp/markdown) — Stable. Import tools from configured local or remote MCP servers. (`tools`, `lifecycle`)
- [AgentMail](https://auggy.dev/docs/augment-agentmail/markdown) — Stable. Send, receive, reply, and forward under policy with durable polling/WebSocket/Svix inbound, human review, and recovery. (`tools`, `transport`, `routes`, `admin`, `audit`)
- [Telegram](https://auggy.dev/docs/augment-telegram/markdown) — Stable. Run text turns through a Telegram bot using polling or webhooks. (`transport`)

### Identity and operations

Recognize returning visitors and move important events outside the active conversation.

- [Visitor Auth](https://auggy.dev/docs/augment-visitor-auth/markdown) — Stable. Verify email ownership and issue a durable recognized-visitor identity. (`tool`, `routes`, `identity`)
- [Notify](https://auggy.dev/docs/augment-notify/markdown) — Stable. Send outbound alerts to named file, webhook, Telegram, or AgentMail destinations. (`tool`, `adapters`)

### Preview

Useful capabilities with security, deployment, or operational edges that still require deliberate setup.

- [Bash](https://auggy.dev/docs/augment-bash/markdown) — Preview. Run allowed host commands or operator-authored scripts. (`tools`)
- [Budgets](https://auggy.dev/docs/augment-budgets/markdown) — Preview. Gate turns using per-thread, rolling, daily, and spend limits. (`turn gate`, `context`, `admin`)
- [Link](https://auggy.dev/docs/augment-link/markdown) — Preview. Exchange authenticated text requests with configured A2A peers. (`tools`, `transport`)

> **Note: Skills are runtime infrastructure**
>
> The skills loader is mounted by **Auggy** and is not a catalog choice. Individual augments may ship skill folders that the loader exposes on demand.

## Choose the next path

| Goal | Guide |
| --- | --- |
| Install a supported capability | [Add an augment](https://auggy.dev/docs/add-augment/markdown) |
| Author project-specific behavior | [Build an augment](https://auggy.dev/docs/build-augment/markdown) |
| Expose model-callable operations | [Tools](https://auggy.dev/docs/add-tools/markdown) |
| Teach a non-obvious workflow | [Skills](https://auggy.dev/docs/add-skills/markdown) |

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
## File Memory

URL: https://auggy.dev/docs/augment-file-memory/markdown
Status: Published
Summary: Persist creator-approved agent-wide behavior in a local file and place it in later turns.
Sections: Keep an operating rule across turns, Generated install, Save a creator-approved behavior, Runtime surfaces, Boundaries, Verify

# File Memory

Canonical: https://auggy.dev/docs/augment-file-memory
Status: Published
Package: auggy 0.5.0

Persist creator-approved agent-wide behavior in a local file and place it in later turns.

## Keep an operating rule across turns

**What it enables:** Store creator-approved, agent-global learned behavior in `learned-behaviors.md` and inject it into later turns.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `memory provider`, `preamble context`

The default provider owns the exact label `learned`. A successful creator-authorized ``memory_write`` replaces the file content, updates the in-process cache, and makes the new guidance available to subsequent turns. The separate top-level `identity: ./identity.md` shorthand also uses file memory, but it is immutable system context rather than this learned-behavior store.

## Generated install

``auggy create <name>`` adds `fileMemory` to `agent.yaml`, creates an empty `<agent>/learned-behaviors.md`, and writes this metadata file at `<agent>/augments/fileMemory/augment.yaml`.

**augments/fileMemory/augment.yaml**

```yaml
type: fileMemory
config:
  label: learned
  source: ./learned-behaviors.md
  mutable: true
  origin: operator
  writeTrustLevels:
    - creator
  priority: high
  placement: preamble
  eviction: drop
```

Relative `source` paths resolve from the agent directory. At boot the provider reads the whole file; a missing primary and fallback source fails startup.

## Save a creator-approved behavior

From a creator-authenticated Console turn, ask the agent to retain one durable operating rule. The model-facing write is:

**Model tool call**

```
memory_write({
  label: "learned",
  content: "Always include an explicit timezone when presenting a deadline."
})
```

Treat the write as complete only when the tool returns ``PERSISTED`:`. The `content` value is the complete new value for the static label, not an append operation.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| Provider | Static memory label `learned`; resolved augment name `fileMemory`. |
| Context | Operator-origin, high-priority preamble context; persistent TTL and drop-on-eviction. |
| ``memory_read`` | Reads `learned` from the boot-loaded cache. |
| ``memory_write`` | Writes `{ label: "learned", content }`; generated policy requires creator trust. |
| ``memory_list`` | Lists `learned` when the current peer may access operator-origin memory. |
| Admin | Reports the source, mutable state, context defaults, cache state, file size, and modification time in Console capabilities. |

The memory bus contributes the generic memory tools. File Memory itself contributes the provider and context, not a private `fileMemory` tool.

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | The generated store accepts writes only from runtime-verified creator turns. Public or agent-trust peers cannot update it. |
| Persistence | Writes are serialized and atomically replace the local file. External file edits are not watched; restart to reload them. |
| Deployment | `learned-behaviors.md` is bundled into a **Railway** image, but it is outside `/app/data`; runtime changes in the container do not survive a replacement or redeploy. |
| Limits | One provider owns one exact label and keeps the whole value in memory. Use Layered Memory for per-peer entries, search, retention, or a database-backed store. |

> **Warning: Do not overlap writable owners**
>
> Do not expose `learned-behaviors.md` through a writable Filesystem mount. Filesystem writes do not invalidate File Memory's cache, so later turns can receive stale context.

## Verify

**Run and inspect the store**

```bash
cd <agent>
auggy run
# In another terminal after the creator-approved write:
cat learned-behaviors.md
```

1. Open ``/console/chat`` through ``auggy run`` so the turn is creator-authenticated.
2. Ask the agent to remember the deadline rule and inspect the ``memory_write`` result for ``PERSISTED`:`.
3. Confirm `learned-behaviors.md` contains the exact saved content.
4. Restart the agent, ask it to present a deadline, and confirm it includes a timezone.
5. Send the same write request without creator authentication and confirm the store is not changed.

## Related

- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Layered Memory](https://auggy.dev/docs/augment-layered-memory/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## Filesystem

URL: https://auggy.dev/docs/augment-filesystem/markdown
Status: Published
Summary: Expose named operator-controlled host paths for file reads, writes, search, and workspace reuse.
Sections: Give the agent a durable workspace, Generated install, Write a reusable report, Runtime surfaces, Boundaries, Verify

# Filesystem

Canonical: https://auggy.dev/docs/augment-filesystem
Status: Published
Package: auggy 0.5.0

Expose named operator-controlled host paths for file reads, writes, search, and workspace reuse.

## Give the agent a durable workspace

**What it enables:** Let the agent read installed skills and create, revise, find, or remove artifacts in an operator-selected workspace.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `6 tools`, `workspace context`, `admin summary`

The model addresses logical paths such as `workspace/reports/q3.md`; the augment maps the first segment to the host path selected by the operator. The default workspace catalog injects bounded filename and metadata hints for creator and agent turns so existing artifacts can be reused without loading file contents automatically.

## Generated install

``auggy create <name>`` adds `filesystem` to `agent.yaml`, creates `<agent>/data/workspace/README.md`, copies the bundled skill to `<agent>/skills/filesystem/`, and writes this file at `<agent>/augments/filesystem/augment.yaml`.

**augments/filesystem/augment.yaml**

```yaml
type: filesystem
config:
  mounts:
    - name: skills
      path: ./skills
      writable: false
    - name: workspace
      path: ./data/workspace
      writable: true
      deletable: true
  workspaceAwareness:
    enabled: true
    maxEntries: 24
    maxDepth: 4
```

Relative mount paths resolve from the agent directory. Add only paths the operator intends the **Auggy** process and model-selected tools to access.

## Write a reusable report

A creator can ask the agent to preserve a report for later work. The model can write it directly to the generated workspace:

**Model tool call**

```
fs_write({
  path: "workspace/reports/weekly.md",
  content: "# Weekly report\n\n- Launch checks passed\n- Follow up on billing alerts\n"
})
```

Parent directories are created automatically. A later turn can find the artifact with ``fs_search`({ path: "workspace", pattern: "**/*.md" })` and read it with ``fs_read``.

## Runtime surfaces

| Surface | Input and behavior |
| --- | --- |
| ``fs_read`` | `{ path }`; reads text, rejects known binary extensions, and truncates at 256 KiB by default. |
| ``fs_list`` | `{ path }`; returns JSON metadata for one file or a directory listing. |
| ``fs_write`` | `{ path, content }`; creates parent directories and writes up to 1 MiB by default. |
| ``fs_mkdir`` | `{ path }`; recursively creates a directory in a writable mount. |
| ``fs_remove`` | `{ path }`; removes a file or empty directory only when the mount is writable and deletable. |
| ``fs_search`` | `{ path, pattern, maxResults? }`; glob search, default 100 results, hard cap 1000. |
| Workspace context | Per-turn policy plus at most 24 catalog paths to depth 4 for creator and agent trust by default; no file contents. |

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | Public turns can see read/list/search tools but not write, mkdir, or remove. Agent-trust turns can write and mkdir but cannot remove. Creator turns still obey each mount's writable and deletable flags. |
| Persistence | Files are ordinary host files. `data/` is gitignored; local persistence lasts until the operator or a permitted tool removes the data. |
| Deployment | **Railway** excludes local `data/` contents from the image, then mounts persistent storage at `/app/data`. New cloud workspace writes persist there, but local workspace files are not uploaded by ``auggy deploy``. |
| Limits | Known binary types are not readable, non-empty directories cannot be removed, search excludes `.git`, ``node_modules``, `.next`, `__pycache__`, and `.DS_Store` by default, and the augment caps filesystem tool calls at 15 per turn. |

> **Warning: Host access, not a sandbox**
>
> A mount grants access to an operator-controlled host path using the **Auggy** process user's permissions. Mount names and per-operation flags narrow the tool API; they are not a container, sandbox, privilege boundary, or general confinement guarantee. Do not mount secrets, credentials, or broad host directories unless that access is intentional.

## Verify

**Inspect the generated workspace**

```bash
cd <agent>
auggy run
# In another terminal after the write:
test -f data/workspace/reports/weekly.md
cat data/workspace/reports/weekly.md
```

1. Confirm ``/console/capabilities`` lists the `skills` read-only mount and writable, deletable `workspace` mount.
2. Ask the agent to create the weekly report and inspect the ``fs_write`` result.
3. Confirm the file exists under `data/workspace/reports/weekly.md` with the expected content.
4. In a later turn, ask for existing Markdown reports and confirm ``fs_search`` finds the same logical path.
5. From an anonymous turn, confirm mutation tools are absent even though read-only filesystem tools remain available.

## Related

- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [File Memory](https://auggy.dev/docs/augment-file-memory/markdown)
## Web Transport

URL: https://auggy.dev/docs/augment-web-transport/markdown
Status: Published
Summary: Serve AG-UI turns, the operator Console, health checks, and runtime discovery.
Sections: Run one agent over HTTP, Generated install, Stream one authenticated turn, Runtime surfaces, Boundaries, Verify

# Web Transport

Canonical: https://auggy.dev/docs/augment-web-transport
Status: Published
Package: auggy 0.5.0

Serve AG-UI turns, the operator Console, health checks, and runtime discovery.

## Run one agent over HTTP

**What it enables:** Accept agent turns over AG-UI SSE and expose the per-agent Console, health endpoint, and runtime discovery on one port.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `transport`, `built-in endpoints`, `health`, `Console`

A client posts messages to `/agent/run`; Web Transport authenticates the request, builds the peer identity, runs the kernel turn, and streams AG-UI events until `RUN_FINISHED`.

## Generated install

``auggy create <name>`` adds `webTransport` to `agent.yaml`, writes the metadata below, and generates `AUGGY_WEB_TOKEN`, `AUGGY_AGENT_ID`, and `AUGGY_PUBLIC_URL=http://localhost:8080` in the gitignored `.env`.

**augments/webTransport/augment.yaml**

```yaml
type: webTransport
config:
  port: 8080
  publicIntegration: false
  auth:
    type: bearer
    token: ${AUGGY_WEB_TOKEN}
  visitorTokens:
    agentBinding: ${AUGGY_AGENT_ID}
```

The current YAML resolver forwards `port`, `auth`, `cors`, `maxMessageLength`, `access.agents`, `concurrency`, `maxQueueDepth`, `rateLimitPerPeer`, `visitorTokens`, `allowAnonymous`, and `publicIntegration`. Do not put TypeScript-only Web Transport options in this YAML file; they are not forwarded by the current resolver.

## Stream one authenticated turn

**AG-UI request**

```bash
cd <agent>
set -a
source .env
set +a
auggy dev &

curl -N http://127.0.0.1:8080/agent/run \
  -H "Authorization: Bearer $AUGGY_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docs-smoke-1" \
  --data '{"threadId":"docs-smoke","messages":[{"role":"user","content":"Reply with: transport ready"}]}'
```

The response is `text/event-stream`. A valid generated bearer authenticates this request as the creator; the stable `threadId` keeps later turns in the same in-process conversation.

## Runtime surfaces

| Method | Path | Current behavior |
| --- | --- | --- |
| `POST` | `/agent/run` | AG-UI SSE turn endpoint. Body requires a non-empty `messages` array; last message content is used. |
| `GET`, `HEAD` | `/` | Public agent info page. A direct TypeScript caller may instead configure a redirect, but that option is not YAML-resolved. |
| `GET`, `POST` | ``/console``, ``/console`/*` | Operator SPA, chat, dashboard APIs, and Console actions. `HEAD` and other methods return 405. |
| `GET` | `/health` | Public JSON liveness response: `{"status":"healthy"}`. |
| `GET`, `HEAD` | `/agent` | Developer integration page only when `publicIntegration: true`; otherwise 404. `/agent/` redirects to it only in that posture. |
| `GET` | `/.well-known/agent-card.json` | Agent card; public with `publicIntegration: true`, otherwise returned only for the web bearer and hidden as 404 from other callers. |
| `OPTIONS` | Any path | `CORS` preflight; configured origins are emitted when `cors` is present. |

Transport defaults are `maxMessageLength: 4000`, `concurrency: 1`, and `maxQueueDepth: 50`. `visitorTokens` are not active merely because the generated config contains `agentBinding`; Visitor Auth enables recognition and supplies the signing key when installed.

> **Note: Advanced preview route hosting**
>
> Web Transport can also dispatch optional augment-defined HTTP routes. That app-integration surface is documented separately and is not required to run an agent.

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | A valid web bearer creates a creator turn; a present but invalid bearer always returns 401. Without a bearer, `allowAnonymous` defaults to true outside production and false in production unless YAML, environment, or a persisted Console override says otherwise. |
| Persistence | The transport does not provide durable conversation storage. Thread history is process memory; restart loses it. Console posture overrides can persist locally in `admin-overrides.json`. |
| Deployment | **Railway** requires the generated port `8080`. Secrets come from `.env` through deploy variables, `/health` is the liveness target, and non-loopback Console access requires HTTPS. |
| Limits | The current transport is HTTP plus SSE, not WebSocket. Closing the client stream does not cancel the running turn, and the AG-UI implementation is a focused subset rather than every protocol event. |

> **Warning: Protect the creator bearer**
>
> The generated bearer proves creator authority on `/agent/run`. Console uses HTTP Basic with a blank username and that token as the password; loopback skips the Console bearer check because local shell access already exposes `.env`. Do not expose plain HTTP Console traffic on a non-loopback interface.

## Verify

**Check liveness and discovery posture**

```bash
curl -s http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/agent
curl -s -H "Authorization: Bearer $AUGGY_WEB_TOKEN" \
  http://127.0.0.1:8080/.well-known/agent-card.json
```

1. Confirm `/health` returns HTTP 200 and `{"status":"healthy"}`.
2. With the generated `publicIntegration: false`, confirm `/agent` returns 404.
3. Confirm the bearer-authenticated agent-card request returns JSON.
4. Run the AG-UI request above and confirm it emits `RUN_STARTED`, assistant text events, and one terminal `RUN_FINISHED`.
5. Open ``/console/capabilities`` and confirm the expected runtime capabilities are loaded.

## Related

- [Transports](https://auggy.dev/docs/transports/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
## Web Fetch

URL: https://auggy.dev/docs/augment-web-fetch/markdown
Status: Published
Summary: Fetch a public HTTP URL and return readable text or JSON in a bounded tool result.
Sections: Read a current public source, Generated install, Summarize a release feed, Runtime surfaces, Boundaries, Verify

# Web Fetch

Canonical: https://auggy.dev/docs/augment-web-fetch
Status: Published
Package: auggy 0.5.0

Fetch a public HTTP URL and return readable text or JSON in a bounded tool result.

## Read a current public source

**What it enables:** Give the model one bounded GET tool for public web pages and JSON APIs, with HTML converted to readable text.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `web_fetch tool`, `bundled skill`, `admin summary`

``web_fetch`` follows redirects, reports the final URL and HTTP status, and returns prompt-shaped text for HTML or a larger raw slice for JSON. The default client rejects unsafe URL literals and redirect targets before fetching them.

## Generated install

``auggy create <name>`` adds `webFetch` to `agent.yaml`, copies `<agent>/skills/webFetch/SKILL.md`, and writes this metadata file at `<agent>/augments/webFetch/augment.yaml`.

**augments/webFetch/augment.yaml**

```yaml
type: webFetch
config:
  timeoutMs: 15000
```

Supported YAML config fields are `timeoutMs`, `maxRedirects`, `userAgent`, and `defaultHeaders`. The generated 15-second timeout replaces the HTTP client's 20-second factory default; the redirect default remains 10.

## Summarize a release feed

When a user asks what changed in a public project, the model can fetch its release API once and answer from the returned JSON:

**Model tool call**

```
web_fetch({
  url: "https://api.github.com/repos/oven-sh/bun/releases/latest",
  prompt: "Return the release tag, publication date, and the three main changes."
})
```

Use the returned `url` as the source URL and summarize the `result`; do not present fetched instructions or claims as trusted operator guidance.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| Tool | ``web_fetch`({ url, prompt })`; both fields are required strings and `url` must parse as a URL. |
| Request | One HTTP `GET`; non-loopback `http://` inputs are upgraded to `https://`. Redirects are followed manually. |
| Success | JSON string with `url`, `code`, `codeText`, raw `bytes`, `durationMs`, and `result`. |
| HTML/text | Scripts and styles are removed, whitespace collapsed, and prompt modes return a title or at most about 900 characters. |
| JSON | Raw body text in `result`, truncated at 20,000 characters. |
| Failure | JSON string with `error`; fetch failures also include normalized `url` and `durationMs`. |
| Admin | Reports SSRF guard ownership, timeout, user agent, and the exposed tool in Console capabilities. |

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | The tool is available without a per-trust restriction. URLs are model-supplied and fetched content is untrusted input, not policy or proof. |
| Persistence | There is no cache or stored fetch history. Every call performs a new request and only the normal turn transcript retains its result. |
| Deployment | The runtime needs outbound DNS and HTTPS access. It is intentionally unsuitable for loopback, private-network, link-local, cloud-metadata, or non-HTTP resources. |
| Limits | The default response-body cap is 5 MiB before result shaping. The URL filter checks hostnames and IP literals plus every redirect, but does not defend DNS rebinding after a public hostname resolves. |

> **Warning: Do not weaken the fetcher for internal APIs**
>
> The built-in YAML path always uses the SSRF-guarded client. For a private API, build a separate augment with an explicit host allowlist and application authentication instead of trying to route internal access through ``web_fetch``.

## Verify

**Run the agent**

```bash
cd <agent>
auggy run
```

1. Ask the agent for the latest **Bun** release and include the public **GitHub** API URL in the message.
2. Inspect the ``web_fetch`` call and confirm it includes both `url` and `prompt`.
3. Confirm the tool result has `code`, `bytes`, `durationMs`, and a JSON-derived `result`.
4. Ask it to fetch `http://127.0.0.1:8080/health` and confirm the result is a structured unsafe-URL error.
5. Repeat the public request and confirm a second network fetch occurs; no cache is expected.

## Related

- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Filesystem](https://auggy.dev/docs/augment-filesystem/markdown)
## Turn Control

URL: https://auggy.dev/docs/augment-turn-control/markdown
Status: Published
Summary: End a blocked turn with a structured input-required result and a visible question.
Sections: Ask one blocking question, Generated install, Resolve a real deployment ambiguity, Runtime surfaces, Boundaries, Verify

# Turn Control

Canonical: https://auggy.dev/docs/augment-turn-control
Status: Published
Package: auggy 0.5.0

End a blocked turn with a structured input-required result and a visible question.

## Ask one blocking question

**What it enables:** Let the agent stop a turn as `input-required`, show a specific question, and resume when the user replies in the same thread.

- **Status:** Core
- **Availability:** Installed by ``auggy create``.
- **Contributes:** `request_input tool`, `turn directive`, `bundled skill`

When the model cannot reasonably proceed without missing user input, ``request_input`` emits the prompt as normal assistant text and terminates the current turn with a structured result. The user's next message starts a new turn in the same conversation.

## Generated install

``auggy create <name>`` adds `turnControl` to `agent.yaml`, copies `<agent>/skills/turnControl/SKILL.md`, and writes this exact metadata file at `<agent>/augments/turnControl/augment.yaml`.

**augments/turnControl/augment.yaml**

```yaml
type: turnControl
```

Turn Control is YAML-configurable. Add `config.requestInputDescription` only when the model needs project-specific selection guidance:

**Supported description override**

```yaml
type: turnControl
config:
  requestInputDescription: >-
    Ask one short question only when a required deployment target is missing
    and no safe default exists. Never use this as a closing pleasantry.
```

## Resolve a real deployment ambiguity

If a user asks to deploy but the agent has two configured production services and no basis for choosing, the model can stop on one answerable choice:

**Model tool call**

```
request_input({
  prompt: "Which production service should I deploy: api-west or api-east?",
  reason: "Two production targets are configured and neither is the default."
})
```

The user sees only `prompt`. `reason` is optional tracing context and is not shown in the assistant reply.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| Tool | ``request_input`({ prompt, reason? })`; `prompt` must be 1-2000 characters. |
| Tool result | Returns `content: prompt` and `terminate: { status: "input-required", message: prompt }`. |
| Assistant output | The prompt is emitted as a normal assistant text message before the terminal event. |
| Kernel result | After the current tool batch settles, the turn ends with status `input-required` and no next model inference runs. |
| AG-UI | `RUN_FINISHED.result` contains `{ status: "input-required", message: prompt }`; HTTP remains 200 SSE. |
| Resume | The next user message starts another turn; clients preserve the thread ID to retain conversation context. |
| Admin | Reports the exposed tool, behavior, and whether the tool description is default or overridden. |

## Boundaries

| Area | Boundary |
| --- | --- |
| Trust | The tool has no trust-level gate. It asks for information; it does not authenticate a user, grant authorization, or confirm that a consequential action is allowed. |
| Persistence | `input-required` is a turn result, not a durable job. Turn Control stores no pending task and performs no background work while waiting. |
| Deployment | The Console understands the result. Other AG-UI clients should branch on `RUN_FINISHED.result.status`; older clients still receive the visible assistant question but may treat the run as normally finished. |
| Limits | It produces only `input-required`. It does not cancel sibling tools already executing in the same model-emitted batch, and it does not produce `auth-required`, failure, cancellation, rejection, deferred execution, retries, or approval workflows. |

> **Warning: Tool guidance is not enforcement**
>
> The default description and bundled skill tell the model not to ask closing pleasantries or avoid defensible decisions. That guidance can reduce misuse but cannot guarantee model selection. Downstream code must treat the structured status as a request for input, not as authorization.

## Verify

**Start a Console turn**

```bash
cd <agent>
auggy run
```

1. Give the agent a task with two equally valid named targets and no default.
2. Inspect the tool call and confirm `prompt` is specific, answerable, and no longer than 2000 characters.
3. Confirm the same prompt appears as the assistant message and the turn ends without another model inference.
4. In the network response, confirm the terminal `RUN_FINISHED.result.status` is `input-required` and `result.message` equals the prompt.
5. Reply with one target in the same thread and confirm the agent continues on a new turn rather than running in the background.

## Related

- [Web Transport](https://auggy.dev/docs/augment-web-transport/markdown)
- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
## Layered Memory

URL: https://auggy.dev/docs/augment-layered-memory/markdown
Status: Published
Summary: Persist and recall peer-scoped episodic memory with the stable SQLite-backed layeredMemory augment.
Sections: Outcome, Install and defaults, Use it, Runtime surfaces, Boundaries, Verify

# Layered Memory

Canonical: https://auggy.dev/docs/augment-layered-memory
Status: Published
Package: auggy 0.5.0

Persist and recall peer-scoped episodic memory with the stable SQLite-backed layeredMemory augment.

## Outcome

**What it enables:** Remember names, preferences, commitments, and recurring topics for the current peer across turns.

- **Status:** Stable
- **Availability:** Install with ``auggy augment add` layeredMemory`.
- **Contributes:** `peer-scoped memory provider`, `memory tools`, `recent-memory context`, `Console administration`

layeredMemory is peer-scoped episodic memory. The default install stores entries in SQLite and gives the shared memory bus a writable namespace; the runtime binds writes and searches to the peer identity on the current turn.

## Install and defaults

**From the agent project**

```bash
auggy augment add layeredMemory
```

**Installed and runtime-created files**

```
agent.yaml                              # adds layeredMemory
augments/layeredMemory/augment.yaml   # generated config
skills/layeredMemory/SKILL.md          # bundled usage guidance
data/memory.db                         # created when the runtime boots
```

**augments/layeredMemory/augment.yaml for an agent named my-agent**

```yaml
type: layeredMemory
config:
  backend: sqlite
  dbPath: ./data/memory.db
  namespace: my-agent
  retentionDays: 90
  autoSave:
    enabled: false
```

The CLI sets `namespace` to the agent name and rewrites the mutable database path under `data/`. No extra package or environment variable is required. Explicit writes work immediately; automatic extraction is off in the generated config.

## Use it

When Sam states a preference that should survive this conversation, write a topic. Do not construct a peer ID or internal label; the runtime derives both from the current turn.

**Save and retrieve a preference**

```ts
memory_write({
  topic: "preferences",
  content: "Sam prefers concise replies with code examples.",
})

memory_search({ query: "concise code examples" })
```

> **Note: Persistence is explicit**
>
> Only tell the caller the preference was saved when the ``memory_write`` result starts with ``PERSISTED``. ``NOT_PERSISTED`` means it was not saved; ``PERSISTENCE_UNKNOWN`` means inspect logs before retrying.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| ``memory_write`({ topic, content, provider? })` | Writes under a runtime-derived label for the current peer. Exact-label namespace writes are refused. |
| ``memory_search`({ query, providers? })` | Runs keyword matching and returns only entries scoped to the current peer. |
| ``memory_list`()` | Lists visible static labels and namespace providers such as `my-agent:*`; it does **not** list stored facts. |
| ``memory_read`({ label })` | Unsupported for layeredMemory because direct label reads would bypass peer scoping; use ``memory_search``. |
| ``memory_forget`({ peerId })` | Deletes all episodic entries for one peer across supporting providers; requires `creator` or `agent` trust. |
| Turn context | Adds up to five recent current-peer entries, plus keyword matches for the incoming message. |
| Console Memory panel | Shows counts and recent entries and exposes a confirmed **Erase peer** action. |

## Boundaries

| Boundary | What to design for |
| --- | --- |
| Trust | Peer isolation depends on runtime identity, not names or claims in chat. A caller cannot select another peer for reads or writes; only elevated trust can erase by peer ID. |
| Persistence | SQLite survives process restarts only while `data/memory.db` survives. Entries expire after the configured retention period; the generated default is 90 days. |
| Identity continuity | Cross-session recall requires the same durable recognized identity, normally from `visitorAuth` or a verified external app-auth assertion. Anonymous web identity is derived from the thread, so a new thread is not the same returning person. |
| Deployment | ``auggy deploy`` excludes local `data/` from the image. On **Railway** the resolver places the SQLite database directly under the admitted `/app/data` volume; it does not rely on a root-level database symlink. Local memories are not uploaded. Keep the SQLite service to one replica; on another platform, mount durable storage at the configured path. |
| Limitations | Search is keyword matching, not vector retrieval. ``memory_read`` is unavailable, ``memory_list`` is provider discovery, and the model-callable erase operation removes all memory for a peer rather than one fact. |

> **Warning: Do not store secrets**
>
> Treat peer memory as durable application data. Do not save credentials, tokens, content marked confidential, or sensitive personal data outside the agent's stated purpose.

## Verify

**Validate and start**

```bash
auggy doctor
auggy run
```

1. In ``/console/chat``, use the Creator caller and ask the agent to remember a specific preference.
2. Open the ``memory_write`` tool result and confirm its first word is ``PERSISTED``.
3. Confirm the database exists with `test -f data/memory.db && echo ok`.
4. Start a new Creator chat and ask about the preference. Inspect ``memory_search`` if the agent performs a targeted lookup.
5. For a browser visitor test, verify the visitor first, then repeat from a new session and confirm the same recognized peer ID is restored.

## Related

- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Visitor Auth](https://auggy.dev/docs/augment-visitor-auth/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
## Knowledge

URL: https://auggy.dev/docs/augment-knowledge/markdown
Status: Published
Summary: Expose read-only local documents and remote knowledge APIs through manifest-driven progressive disclosure.
Sections: Outcome, Install and defaults, Use it, Runtime surfaces, Boundaries, Verify

# Knowledge

Canonical: https://auggy.dev/docs/augment-knowledge
Status: Published
Package: auggy 0.5.0

Expose read-only local documents and remote knowledge APIs through manifest-driven progressive disclosure.

## Outcome

**What it enables:** Keep a small source and endpoint catalog in context, then fetch full reference content only when a turn needs it.

- **Status:** Stable
- **Availability:** Install with ``auggy augment add` knowledge`.
- **Contributes:** `knowledge_fetch tool`, `system context`, `bundled skill`

Knowledge is a read-only progressive-disclosure augment. Each source manifest contributes organization metadata and endpoint descriptions to context; ``knowledge_fetch`` loads one listed endpoint on demand instead of placing every document in every prompt.

## Install and defaults

**From the agent project**

```bash
auggy augment add knowledge
```

**Generated files**

```
agent.yaml                         # adds knowledge
augments/knowledge/augment.yaml    # generated config
skills/knowledge/SKILL.md           # bundled usage guidance
knowledge/README.md
knowledge/sources.json
knowledge/local/manifest
knowledge/local/mission.md
knowledge/local/context.md
```

**augments/knowledge/augment.yaml**

```yaml
type: knowledge
config:
  root: ./knowledge
```

**knowledge/sources.json**

```json
{
  "sources": [
    {
      "name": "local",
      "description": "Local project knowledge maintained with this agent",
      "baseUrl": "file://./local"
    }
  ]
}
```

**knowledge/local/manifest for my-agent**

```json
{
  "org": "my-agent",
  "purpose": "project knowledge for this agent",
  "creator": "the creator",
  "phase": "active",
  "endpoints": [
    {
      "path": "/mission",
      "description": "Agent purpose, project context, and active focus"
    },
    {
      "path": "/context",
      "description": "Project background, terminology, workflows, and policies"
    }
  ]
}
```

If `agent.yaml` already has `purpose` or `creator.displayName`, the scaffold writes those values into the manifest. The starter markdown files contain placeholders for project-owned content.

## Use it

Add a pricing document, advertise its exact endpoint, restart after changing the manifest, and fetch it from a turn that needs billing facts.

**knowledge/local/pricing.md**

```
# Pricing

The Pro plan is $49 per month and includes five seats.
```

**Add to knowledge/local/manifest endpoints**

```json
{
  "path": "/pricing",
  "description": "Current plans, prices, included seats, and billing policy"
}
```

**Fetch the listed endpoint**

```ts
knowledge_fetch({
  source: "local",
  endpoint: "/pricing",
})
```

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| System context | Lists each loaded source, its description, organization metadata, and every advertised endpoint path and description. |
| ``knowledge_fetch`({ source, endpoint, prompt? })` | Fetches one exact manifest-listed endpoint from a local `file://` source or remote HTTP(S) source and returns a JSON envelope. |
| Local source | Reads the literal endpoint path under the source directory, then tries a `.md` suffix; traversal and symlink escapes are rejected. |
| Remote source | Loads `GET /manifest`, then issues `GET` for the selected listed path. `token` or `tokenEnv` can supply a bearer token. |
| Boot diagnostics | Logs loaded source and endpoint counts; an unavailable or invalid manifest produces warnings and an empty knowledge context instead of stopping the agent. |

## Boundaries

| Boundary | What to design for |
| --- | --- |
| Trust | The manifest is an endpoint allowlist, **not** caller authorization. Every listed endpoint is available to every caller that receives ``knowledge_fetch``; do not list privileged or secret content. |
| Persistence | The augment has no write surface. Sources are loaded for the process lifetime and manifests cache for one hour by default, so restart after adding a source or when immediate manifest changes matter. |
| Deployment | Local `knowledge/` sources are copied into the deployment image, not written to the **Railway** volume. Cloud edits require a rebuild and redeploy; remote source content stays at its configured API. |
| Prompt parameter | `prompt` is returned as a hint in supported response envelopes. It does **not** search, filter, summarize, or reduce the retrieved endpoint content. |
| Limitations | Endpoint matching is exact and content is capped at about 20,000 characters. Manifest `method: POST` is display metadata; ``knowledge_fetch`` remains read-only and fetches with `GET`. |

> **Warning: Descriptions guide selection, not access**
>
> Prompt instructions may encourage the model to fetch only relevant endpoints, but they do not hide endpoints or enforce per-caller policy. Split sensitive material into a separately authorized capability instead of relying on wording.

## Verify

**Validate and start**

```bash
auggy doctor
auggy run
```

1. Confirm startup logs contain `[knowledge] loaded local knowledge` and the expected endpoint count.
2. In ``/console/chat``, ask a question that requires the new endpoint and inspect the ``knowledge_fetch`` call.
3. Confirm the tool result names `source: local`, reports `endpoint: /pricing`, and contains the text from `pricing.md`.
4. Call ``knowledge_fetch`({ source: "local", endpoint: "/not-listed" })` and confirm it returns a manifest refusal with no content.
5. For a deployed agent, redeploy after editing local knowledge and repeat the fetch against the production Console.

## Related

- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## MCP

URL: https://auggy.dev/docs/augment-mcp/markdown
Status: Published
Summary: Import tools from configured local or remote MCP servers and expose them as namespaced Auggy tools.
Sections: What it enables, Install and configure, Use one server, Runtime surfaces, Boundaries, Verify

# MCP

Canonical: https://auggy.dev/docs/augment-mcp
Status: Published
Package: auggy 0.5.0

Import tools from configured local or remote MCP servers and expose them as namespaced **Auggy** tools.

## What it enables

**What it enables:** Your agent can discover and call tools from each configured MCP server through namespaced tools such as ``mcp_ops_read_status``.

- **Status:** Stable
- **Availability:** Install with ``auggy augment add` mcp`. The augment is optional and is enabled by `agent.yaml`.
- **Contributes:** `tools`, `lifecycle`, `admin info`

MCP is an import boundary. **Auggy** starts or connects to the configured server, discovers its tools during boot, and makes those tools available to the model. It does not expose an MCP server endpoint.

## Install and configure

1. Run ``auggy augment add` mcp` from the agent project. This enables the augment and creates `.mcp.json` when needed.
2. Keep server definitions in `.mcp.json` at the agent root. Keep bearer tokens and other secrets in `.env`.
3. Run `auggy mcp doctor` before starting the agent. Use `auggy mcp doctor --cloud` before a cloud deploy.

**agent.yaml**

```yaml
augments:
  - mcp
```

**.mcp.json**

```json
{
  "mcpServers": {
    "ops": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OPS_MCP_TOKEN}"
      }
    }
  },
  "auggy": {
    "servers": {
      "ops": {
        "allowedTools": ["read_status", "create_ticket"],
        "blockedTools": ["delete_all"],
        "allowedTrustLevels": ["creator", "agent"],
        "toolPolicies": {
          "create_ticket": {
            "allowedTrustLevels": ["creator", "agent"]
          }
        }
      }
    }
  }
}
```

**.env**

```env
OPS_MCP_TOKEN=replace-with-the-server-token
```

> **Note: Source of truth**
>
> `agent.yaml` enables MCP. `.mcp.json` owns server connection and **Auggy** policy. Do not copy server commands or headers into `agent.yaml`.

## Use one server

A support agent can use a small, allowlisted operations server to check an incident and create a ticket only after the operator has admitted those tools.

**Agent request**

```
Check the current checkout incident. Use mcp_ops_read_status first. If it is still active, create one ticket with the incident ID and customer impact summary.
```

The discovered tools are exposed as ``mcp_ops_read_status`` and ``mcp_ops_create_ticket``; the server's unprefixed names are not placed directly in the **Auggy** tool namespace.

## Runtime surfaces

| Surface | Current behavior | Exact shape |
| --- | --- | --- |
| Model tools | Discovered MCP tools are callable during turns. | `mcp_<server>_<tool>` |
| Boot lifecycle | Connects to each enabled server and paginates tool discovery. | `onBoot` |
| Shutdown lifecycle | Closes active MCP connections. | `onShutdown` |
| Tool policy | Filters names and compiles trust restrictions before model exposure. | `.mcp.json` `auggy.servers.<name>` |
| Operator view | Reports config path, tool count, server state, restricted count, and errors. | MCP `adminInfo` |

## Boundaries

| Boundary | Current behavior |
| --- | --- |
| Trust | Treat remote descriptions, errors, and results as untrusted content. Destructive or open-world annotated tools default to creator-only. `allowedTrustLevels` and per-tool `toolPolicies` can narrow or explicitly widen exposure. |
| Persistence | MCP keeps connection and discovery state in the running process. Server definitions persist in `.mcp.json`; referenced secrets persist wherever the operator manages `.env`. |
| Deployment | Local `stdio` is for local development. Cloud agents need HTTPS remote MCP, or a local `stdio` server marked `cloud: "disabled"` or `cloud: "localOnly"`. |
| Limits | Defaults are 30s call timeout, four concurrent calls per server, 64 tools, 20 discovery pages, 128 KiB results, and 16 KiB input schemas. Failed servers expose no tools and do not crash boot. |
| Scope | This augment imports tools only. It does not ingest MCP resources or prompts as **Auggy** capabilities and does not provide an MCP server transport. |

## Verify

1. Run `auggy mcp doctor` and resolve missing environment references, invalid transports, or literal secret warnings.
2. Start the agent with ``auggy run`` and confirm the MCP server is connected in the Console integration details.
3. Ask for a task that requires the configured tool and confirm the model selects the namespaced `mcp_<server>_<tool>` tool.
4. Run `auggy mcp doctor --cloud` before deploying. Confirm local-only servers are explicitly disabled for cloud and remote URLs use HTTPS.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [MCP](https://auggy.dev/docs/mcp/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
## AgentMail

URL: https://auggy.dev/docs/augment-agentmail/markdown
Status: Published
Summary: Give an agent a policy-gated inbox with durable inbound delivery, send, reply, and forward tools, creator review, and recovery.
Sections: What it enables, Install and configure, Choose and admit the arrival path, Send, reply, forward, and review, Persistence, operations, and limits, Verify the inbox

# AgentMail

Canonical: https://auggy.dev/docs/augment-agentmail
Status: Published
Package: auggy 0.5.0

Give an agent a policy-gated inbox with durable inbound delivery, send, reply, and forward tools, creator review, and recovery.

## What it enables

**What it enables:** Incoming email can wake the agent. The agent can send, reply, or forward under trust, recipient, content, rate, and review policies you control.

- **Status:** Stable
- **Availability:** Available in `auggy@0.5.0`. Inbound email is off by default; enable polling, WebSocket, or verified webhook delivery with an explicit sender allowlist.
- **Contributes:** `tools`, `transport`, `routes`, `SQLite ledger`, `admin controls`

> **Note: Use AgentMail for email conversations**
>
> Use this augment when incoming email should become an agent turn or the agent needs to continue a thread. Use `notify` for one-way alerts and `visitorAuth` only for magic-link delivery. If you need occasional operator-driven mail actions without an inbox in the runtime, AgentMail MCP may be simpler.

## Install and configure

1. Run ``auggy augment add` agentMail` from the agent project.
2. Run `auggy augment setup agentMail`, or set `AGENTMAIL_API_KEY` and `AGENTMAIL_INBOX_ID` in `.env`.
3. To receive email, choose one inbound mode and add a non-empty exact/domain sender allowlist.
4. If public email turns may reply, add `public` to `outbound.allowedTrustLevels` and keep it in `humanReview.requiredForTrustLevels` so replies queue for creator approval.
5. Keep `webTransport` mounted. Webhook mode needs its verified route; executable human review needs the creator admin route.

**.env**

```env
AGENTMAIL_API_KEY=am_replace_me
AGENTMAIL_INBOX_ID=support@agentmail.to
# Webhook mode only:
AGENTMAIL_WEBHOOK_SECRET=whsec_replace_me
```

**augments/agentMail/augment.yaml**

```yaml
type: agentMail
config:
  apiKey: ${AGENTMAIL_API_KEY}
  inboxId: ${AGENTMAIL_INBOX_ID}
  dbPath: ./agent-mail.db
  outbound:
    allowedTrustLevels:
      - creator
      - public
    allowedRecipients:
      - "*@customer.example"
    subjectPrefix: "[Auggy] "
    maxRecipients: 10
    bodyMaxBytes: 102400
    allowHtml: false
    rateLimit:
      globalMaxPerHour: 10
      perRecipientCooldownMs: 300000
      dedupWindowMs: 300000
    humanReview:
      requiredForTrustLevels:
        - public
      expiresAfterMs: 86400000
  inbound:
    mode: websocket
    allowedSenders:
      - "*@customer.example"
    pollIntervalMs: 60000
    maxPromptBytes: 102400
    maxAttempts: 5
    classifications:
      received: process
      spam: discard
      blocked: discard
      unauthenticated: discard
```

> **Note: Webhook mode**
>
> Replace `mode: websocket` with `mode: webhook` and optionally set `webhook.path`, `webhook.secretEnv`, and `webhook.timestampToleranceSeconds`. Defaults are `/webhooks/agentmail`, `AGENTMAIL_WEBHOOK_SECRET`, and 300 seconds.

## Choose and admit the arrival path

| Mode | Live arrival | Durable recovery | Use when |
| --- | --- | --- | --- |
| none | Disabled | No inbound ledger worker | The agent only sends new email |
| polling | Periodic REST reads | Checkpointed reads are the arrival and catch-up path | A simple one-minute default cadence is enough |
| websocket | Reconnectable AgentMail subscription | REST catch-up runs after subscription | You need low latency without a public callback |
| webhook | Svix-verified POST route | REST catch-up runs at boot; the ledger deduplicates provider retries | The agent has a stable public URL |

Every enabled mode drains the same SQLite ledger. Provider delivery and message IDs are deduplicated; catch-up starts with a 24-hour first-run lookback and advances a checkpoint with one minute of overlap; workers lease one message, retry failed turns with bounded backoff, and durably mark processed or discarded outcomes.

> **Warning: One inbound owner per inbox**
>
> Only one enabled inbound AgentMail augment may own an inbox. Multiple outbound-only instances can coexist, but competing inbound workers are rejected.

| Gate | Default behavior |
| --- | --- |
| Sender | Enabled inbound requires `allowedSenders`; exact addresses and `*@domain` patterns compare case-insensitively. |
| Classification | Ordinary received mail is processed. Spam, blocked, and unauthenticated events are discarded unless explicitly overridden. |
| Identity | The sender becomes a deterministic `public` + `anonymous` peer scoped to the inbox, sender, and thread. |
| Prompt | The provider envelope is rendered as bounded, explicitly untrusted JSON. Email content never becomes a system instruction. |
| Failure | A failed turn retries up to `maxAttempts` (default 5), then the ledger durably discards it. |

## Send, reply, forward, and review

| Tool | Use | Important boundary |
| --- | --- | --- |
| `send_message` | Start a new message | Trust, recipient, content, rate, dedup, and review policy all run before the provider call |
| `reply_to_message` | Continue the triggering email thread | The ID must have been delivered in this turn; real reply recipients are rechecked against policy |
| `forward_message` | Hand the triggering message to another recipient | The ID must have been delivered in this turn and forward recipients are policy-checked |

A configured review trust level receives `status: "`pending_review`"`, not `sent`. The exact queued request is stored with an immutable fingerprint and expires after 24 hours by default. The redacted admin row links to a creator-authenticated, `no-store` detail route; approval requires its fingerprint and rechecks current rate limits.

> **Note: Sensitive content is flagged, not rewritten**
>
> **Auggy** scans outbound text for token-shaped secrets and marks matches in the operator audit surface. It does not block or rewrite the message; use trust, recipient, and review policies to decide whether it can be sent.

> **Warning: Never retry an ambiguous send**
>
> AgentMail sends do not accept an idempotency key. When the provider may have accepted a request before the connection failed, **Auggy** marks the durable attempt ambiguous. Inspect AgentMail and reconcile it as sent or not sent through the admin action; blind retry can duplicate real email.

## Persistence, operations, and limits

Locally, relative AgentMail state resolves from the agent project. On **Railway** it is namespaced under `/app/data/agent-mail/<augment-name>`. Startup requires the real `/app/data` volume, creates the AgentMail state directory with mode 0700, and proves fsync plus atomic rename durability before the agent starts.

- Inspect inbound mode/live state, ledger counts, checkpoint, catch-up summary, last event, worker outcome, and provider error.
- Inspect redacted dispatch and review rows; exact review content requires creator authentication.
- Send a test message, adjust the hourly cap, approve or reject queued mail, and reconcile ambiguous attempts.
- Do not add root-level SQLite symlinks. Core stores resolve directly to the **Railway** volume; only Link retains a compatibility symlink.

- Outbound attachments are not exposed.
- Drafts, read receipts, retraction, and delivery-event turns are not exposed.
- An inbound turn receives the triggering message, not an automatically fetched full thread transcript.
- The `notify` AgentMail adapter and `visitorAuth` magic-link delivery remain separate outbound-only concerns.

## Verify the inbox

1. Run `auggy@0.5.0` and confirm the inbox healthcheck and inbound runtime are ready in the creator admin surface.
2. Send one allowed ordinary email and confirm it becomes a public anonymous turn exactly once.
3. Restart the agent, send mail while it is offline, and confirm REST catch-up processes the missed message without duplicating the earlier one.
4. Send mail from an off-allowlist sender and a discarded classification; confirm neither reaches the model and both outcomes are visible in ledger counts.
5. From an admitted public email turn, propose a reply. Confirm the tool returns ``pending_review``, inspect the exact request as creator, then approve with the matching fingerprint.
6. On **Railway**, confirm the volume is mounted at `/app/data` and AgentMail state lands beneath `/app/data/agent-mail/<augment-name>` after redeploy.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Notify](https://auggy.dev/docs/augment-notify/markdown)
- [Visitor Auth](https://auggy.dev/docs/augment-visitor-auth/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
## Telegram

URL: https://auggy.dev/docs/augment-telegram/markdown
Status: Published
Summary: Run text turns through a Telegram bot with polling or webhooks and static operator-configured identity lists.
Sections: What it enables, Install and configure, Use a Telegram operations bot, Runtime surfaces, Boundaries, Verify

# Telegram

Canonical: https://auggy.dev/docs/augment-telegram
Status: Published
Package: auggy 0.5.0

Run text turns through a Telegram bot with polling or webhooks and static operator-configured identity lists.

## What it enables

**What it enables:** A Telegram text message becomes an **Auggy** turn, and the agent sends its text reply back to the same Telegram chat.

- **Status:** Stable
- **Availability:** Install with ``auggy augment add` telegramTransport`. Configure a Telegram bot token and one inbound mode.
- **Contributes:** `transport`, `text inbound`, `text outbound`

Identity is resolved from static Telegram user-ID configuration. This transport does not dynamically integrate with `visitorAuth`; configure creator, admitted-agent, and recognized-user IDs directly.

## Install and configure

1. Create a bot with @BotFather and put its token in `.env`.
2. Find the operator's numeric Telegram user ID, set `TELEGRAM_CREATOR_USER_IDS`, and send the bot a first message.
3. Run ``auggy augment add` telegramTransport`. The default is polling; use webhook mode only with a public HTTPS endpoint.

**.env**

```env
TELEGRAM_BOT_TOKEN=replace-with-botfather-token
TELEGRAM_CREATOR_USER_IDS=123456789
```

**augments/telegramTransport/augment.yaml**

```yaml
type: telegramTransport
config:
  botToken: ${TELEGRAM_BOT_TOKEN}
  inbound:
    mode: polling
    polling:
      timeoutSec: 30
  auth:
    creatorUserIds: []
    creatorUserIdsEnv: TELEGRAM_CREATOR_USER_IDS
    anonymousIdentityMode: ephemeral
```

**Webhook production variant**

```yaml
type: telegramTransport
config:
  botToken: ${TELEGRAM_BOT_TOKEN}
  inbound:
    mode: webhook
    webhook:
      publicUrl: https://agent.example.com/telegram
      port: 8081
      secretToken: ${TELEGRAM_WEBHOOK_SECRET}
      allowedUpdates:
        - message
  auth:
    creatorUserIds: []
    creatorUserIdsEnv: TELEGRAM_CREATOR_USER_IDS
    anonymousIdentityMode: ephemeral
```

## Use a Telegram operations bot

A creator can use a private Telegram chat to check a deployment without opening the web console. The creator ID is resolved before the turn, so creator-only tools and policies remain available.

**Telegram DM to the bot**

```
Check the latest deployment status, report any failed health checks, and do not change production.
```

The inbound thread is `tg-chat-<chatId>`. The reply is sent with Telegram `sendMessage` to the chat that produced the turn.

## Runtime surfaces

| Surface | Current behavior | Exact shape |
| --- | --- | --- |
| Polling ingress | Long-polls Telegram and dispatches text updates. | `getUpdates` with `inbound.polling.timeoutSec` (default 30) |
| Webhook ingress | Runs a **Bun** HTTP server and accepts authenticated Telegram POST updates. | `POST` on `inbound.webhook.port` (default 8081) |
| Kernel handoff | Creates a message trigger and calls the shared kernel turn path. | `transport.register` + `kernel.handleInbound` |
| Reply egress | Concatenates text parts and replies to the originating chat. | Telegram Bot API `sendMessage` |
| Thread identity | Maps one Telegram chat to one **Auggy** thread. | `tg-chat-<chatId>` |

## Boundaries

| Boundary | Current behavior |
| --- | --- |
| Trust | Private-chat user IDs in `creatorUserIds` resolve to creator. `admittedAgents` resolve to agent, `recognizedUserIds` to recognized public, and all other users to anonymous public. Group messages are not promoted to creator by the creator ID alone. A failed admitted-agent boot health check logs a warning but does not remove that configured agent mapping. |
| Persistence | Thread history, memory, and budgets use **Auggy**'s configured stores. Anonymous IDs are ephemeral by default (`tg_anon_<threadId>`); `durable` uses `tg_user_<userId>` across chats. Telegram polling offset and the thread-to-chat reply map are process-local. |
| Deployment | Polling needs no public HTTPS endpoint and works with the generated **Railway** service. Webhooks need a publicly reachable HTTPS URL, forwarded `X-Telegram-Bot-Api-Secret-Token`, and one active mode per bot. The generated **Railway** deployment exposes only Web Transport on port 8080, so webhook mode on its separate port requires custom ingress or external routing. |
| Transport | Inbound and reply messages are text-only. There is no streaming edit, media, attachment, or file-message handling in this transport. Use `notify` for proactive Telegram messages to configured destinations. |
| Auth model | Auth lists are static config and environment-backed numeric IDs. There is no dynamic `visitorAuth` handoff or app-login bridge in this augment. |

## Verify

1. Start the agent with ``auggy run`` and confirm Telegram is running in the Console integration details.
2. Send a text DM to the bot and confirm one turn is recorded with the expected `tg-chat-<chatId>` thread.
3. Confirm the text reply arrives in the same chat. If the turn fails, verify that the user-safe failure text does not expose provider credentials.
4. For webhook mode, send a POST with the configured secret header and inspect Telegram `getWebhookInfo` if updates do not arrive.
5. Check the identity path with a creator, admitted agent, recognized user, and unknown user before enabling sensitive tools.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Web Transport](https://auggy.dev/docs/augment-web-transport/markdown)
- [Turn Control](https://auggy.dev/docs/augment-turn-control/markdown)
- [Notify](https://auggy.dev/docs/augment-notify/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## Visitor Auth

URL: https://auggy.dev/docs/augment-visitor-auth/markdown
Status: Published
Summary: Verify email ownership and restore one recognized public identity across browser sessions.
Sections: Recognize a returning visitor, Install locally, then configure delivery, Choose the model or application path, Runtime surfaces, Production boundaries, Verify identity and trust separately

# Visitor Auth

Canonical: https://auggy.dev/docs/augment-visitor-auth
Status: Published
Package: auggy 0.5.0

Verify email ownership and restore one recognized public identity across browser sessions.

## Recognize a returning visitor

**What it enables:** Turn an anonymous browser visitor into a durable `public` + `recognized` identity after they prove control of an email address.

- **Status:** Stable
- **Availability:** Add with ``auggy augment add` visitorAuth`; run setup before production email delivery.
- **Contributes:** `request_auth tool`, `3 HTTP routes`, `identity lookup`, `SQLite store`, `admin controls`

> **Note: Recognition is not elevation**
>
> Verification proves control of an email address. The caller remains at `public` trust; it does not grant `creator`, `agent`, application roles, or permission to consequential tools.

## Install locally, then configure delivery

**Recommended setup**

```bash
auggy augment add layeredMemory visitorAuth
auggy augment setup visitorAuth
auggy doctor --cloud
```

**augments/visitorAuth/augment.yaml**

```yaml
type: visitorAuth
config:
  publicUrl: ${AUGGY_PUBLIC_URL}
  dbPath: ./data/visitor-auth.db
  agentMail:
    transport: agentmail
    apiKey: ${AGENTMAIL_API_KEY}
    inboxId: ${AGENTMAIL_INBOX_ID}
    subjectPrefix: "[Verify] "
  signingKey: ${VISITOR_SIGNING_KEY}
  rateLimit:
    perHour: 1
    perDay: 3
  reverifyAfterDays: 90
  tokenTtlMinutes: 15
  layeredMemoryDbPath: ./data/memory.db
```

A fresh local install uses `agentMail.transport: console` and prints verification links to the agent process. `auggy augment setup visitorAuth` configures AgentMail for production. Cloud preflight rejects console delivery unless you explicitly accept links appearing in service logs.

## Choose the model or application path

### Let the agent request verification

**Conversation.** Use when the visitor asks to be remembered during an active turn. The augment requires the email to appear in recent visitor messages.

**request_auth input**

```json
{
  "method": "email",
  "email": "sam@example.com"
}
```

### Submit a sign-in form directly

**Application.** Use the deterministic route when a frontend owns the form. This path does not migrate an existing anonymous chat identity.

**Request a link**

```bash
curl -X POST "$AUGGY_URL/visitor-auth/request" \
  -H 'content-type: application/json' \
  --data '{"email":"sam@example.com"}'
```

The verification page uses `GET` to display confirmation without consuming the token. Its `POST` consumes the token atomically and writes the signed visitor token to same-origin browser storage.

## Runtime surfaces

| Surface | Behavior |
| --- | --- |
| ``request_auth`` | Sends a magic link from the active anonymous turn after validating recent-message email evidence and per-email rate limits. |
| `POST /visitor-auth/request` | Deterministic public form endpoint; issues a link without binding arbitrary anonymous chat history. |
| `GET /visitor-auth/verify` | Renders the confirmation page without consuming the one-time token. |
| `POST /visitor-auth/verify` | Consumes the token, records verification, returns a signed visitor token, and can migrate current-turn memory when safely bound. |
| Route auth | Enables `visitor.optional` and `visitor.required` for augment routes through Web Transport. |
| SQLite | Stores issued tokens, recognized visitors, revocations, and first-verification notification state. |
| Admin and CLI | Lists and revokes recognized visitors through Console and `auggy visitors`. |

## Production boundaries

- A recognized visitor is still `public`. Add route/tool authorization requirements for application roles or grants.
- The model tool requires the email to appear in one of the visitor's recent messages; the deterministic route instead relies on body validation and per-email throttling.
- Identity continuity depends on the signed `x-visitor-token` and same-origin browser storage. Rotating `VISITOR_SIGNING_KEY` invalidates existing tokens.
- SQLite must live on durable storage. **Railway** persists `./data/visitor-auth.db`; use one process for the local database.
- Rate-limit evidence is process-local and resets on restart. Revocation is durable and denylisted rather than deleting the verification record.

## Verify identity and trust separately

1. Start locally, ask an anonymous visitor to verify an email they typed, and open the printed confirmation link.
2. Submit the confirmation page and confirm `auggy visitors <agent>` lists a stable `vis_...` identity.
3. Start a new same-origin browser session and confirm the recognized identity is restored.
4. With Layered Memory installed, confirm remembered context follows that recognized visitor rather than a display name.
5. Call a creator-only operation and confirm email verification alone does not authorize it.

## Related

- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Layered Memory](https://auggy.dev/docs/augment-layered-memory/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## Notify

URL: https://auggy.dev/docs/augment-notify/markdown
Status: Published
Summary: Send a bounded outbound alert to an operator-selected file or remote destination.
Sections: Move an important event outside chat, Start with the local destination, Escalate one operational event, Runtime surfaces, Production boundaries, Verify before adding a remote adapter

# Notify

Canonical: https://auggy.dev/docs/augment-notify
Status: Published
Package: auggy 0.5.0

Send a bounded outbound alert to an operator-selected file or remote destination.

## Move an important event outside chat

**What it enables:** Let the agent escalate or report an event to a named operator destination without turning that channel into an inbound conversation.

- **Status:** Stable
- **Availability:** Add with ``auggy augment add` notify`; the default destination writes a local JSONL file.
- **Contributes:** `notify tool`, `4 outbound adapters`, `rate and dedup policy`, `admin controls`

Notify is for out-of-band operational messages: an escalation, requested status update, or event that needs human attention. It is not email conversation management, Telegram ingress, or a general queue.

## Start with the local destination

**Add Notify**

```bash
auggy augment add notify
```

**augments/notify/augment.yaml**

```yaml
type: notify
config:
  destinations:
    - name: creator
      transport: log-to-file
      path: ./data/notifications.jsonl
      allowedTrustLevels:
        - creator
        - agent
  rateLimit:
    cooldownMs: 120000
    globalMaxPerHour: 5
    dedupWindowMs: 300000
    dedupThreshold: 0.6
    perPeerCooldownMs: 30000
```

Replace or extend `destinations` with `webhook`, `telegram`, or `agentmail` adapters when local JSONL is no longer enough. Keep destination credentials in environment variables.

## Escalate one operational event

**notify input**

```json
{
  "to": "creator",
  "summary": "Checkout smoke test failed after the staging deploy.",
  "reason": "The release should not be promoted until the failure is reviewed."
}
```

The result is `sent`, ``rate_limited``, or `failed`. For remote adapters, `sent` means the adapter or provider accepted the message; it is not a read receipt or proof that a person acted on it.

## Runtime surfaces

| Surface | Behavior |
| --- | --- |
| `notify({ to, summary, reason?, visitor? })` | Sends one concise message to a configured destination name. |
| `log-to-file` | Appends one JSON record to the configured file. |
| `webhook` | Posts a JSON payload to the configured endpoint. |
| `telegram` | Calls Telegram `sendMessage` for a configured chat. |
| `agentmail` | Sends new outbound email through configured AgentMail credentials. |
| Admin | Reports destinations and recent outcomes and supports a persistent daily-cap override. |
| Inbound | None. Notify never creates an **Auggy** turn from a response. |

## Production boundaries

- Destinations default to `creator` and `agent` trust. Admitting `public` requires explicit policy and can require an escalation reason.
- Creator calls bypass notification rate limits. Rate and dedup state for other peers is process-local, resets on restart, and is not coordinated across replicas.
- Failed delivery does not consume quota. Successful remote API acceptance does not prove human delivery or reading.
- Recent events are in memory. The local JSONL destination and admin cap override persist; remote providers own their delivery records.
- Use the separate AgentMail augment for email conversations, including inbound turns, replies, and forwarding, and Telegram Transport for bidirectional Telegram chat; Notify remains outbound-only.

## Verify before adding a remote adapter

1. Keep the generated `log-to-file` destination and start the agent as creator.
2. Ask for the test notification above and confirm the tool returns `sent`.
3. Inspect `data/notifications.jsonl` and confirm it contains one bounded event without provider secrets.
4. Repeat from a `public` auth context and confirm the destination trust policy denies the call.
5. After configuring a remote adapter, repeat once and verify both the **Auggy** result and the provider-side delivery record.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [AgentMail](https://auggy.dev/docs/augment-agentmail/markdown)
- [Telegram](https://auggy.dev/docs/augment-telegram/markdown)
- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
## Bash

URL: https://auggy.dev/docs/augment-bash/markdown
Status: Preview
Summary: Run explicitly configured host commands or operator-authored scripts.
Sections: Outcome, Install and configure, Use it, Runtime surfaces, Boundaries, Verify

# Bash

Canonical: https://auggy.dev/docs/augment-bash
Status: Preview
Package: auggy 0.5.0

Run explicitly configured host commands or operator-authored scripts.

## Outcome

**What it enables:** Give a creator-scoped turn the ability to inspect or operate on the **Auggy** host.

- **Status:** Preview
- **Availability:** Install with ``auggy augment add` bash`.
- **Contributes:** `tools`

Bash executes child processes on the host. It is useful for bounded inspection and operator-authored maintenance scripts, but it does not create a sandbox.

## Install and configure

1. Run ``auggy augment add` bash` in the agent project and confirm the Preview prompt.
2. Review `augments/bash/augment.yaml`; the bundled skill is copied to `skills/bash/SKILL.md`.
3. Run ``auggy doctor``, then restart the agent after changing this file.

**augments/bash/augment.yaml**

```yaml
type: bash
config:
  risk: restricted
  allowedCommands:
    - echo
    - ls
    - cat
    - pwd
    - date
```

This is the catalog default. `restricted` requires `allowedCommands`; adding an allowlist forces exec mode, so shell pipes, redirects, chaining, and command substitution are not interpreted.

## Use it

A creator can inspect the agent workspace without enabling unrestricted shell features. The tool receives a command and, in restricted mode, an argument array.

**shell_exec input**

```json
{
  "command": "ls",
  "args": ["-la"]
}
```

The result is JSON with `stdout`, `stderr`, `exitCode`, `durationMs`, and `truncated`. Keep commands read-only unless the host and trust policy are deliberately controlled.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| `shell_exec` | Input `{ command, args? }`; executes one command and returns JSON process results. |
| `run_script` | Available when `scripts` is non-empty; input `{ name }`; runs one operator-authored script. |
| Trust gate | ``shell_exec`` and ``run_script`` are hidden from `public` and `agent` peers by default; creator gets them. |
| Limits | Default timeout 30,000 ms, 262,144 bytes per output stream, and 10 tool calls per turn. |

## Boundaries

| Area | Current boundary |
| --- | --- |
| Trust | Host execution is creator-only by default. An explicit `perTrustLevel` override can expose tools to an agent peer; do not expose them to public traffic. |
| Persistence | Bash has no execution-state store. Commands can read or mutate the host filesystem and processes; only the current tool result returns to the turn. |
| Deployment | The child runs in the same host or container boundary as **Auggy**. A container is an operational boundary, not a Bash sandbox. |
| Limitations | `standard` enables shell syntax, `unrestricted` also inherits the full environment, and blocklists are not a complete security policy. Timeouts kill the process group; output is capped and can be truncated. |

> **Warning: Not a sandbox**
>
> Bash is host process execution, not a sandbox. Use a separate hardened execution service when commands or data are not fully trusted.

## Verify

1. Run ``auggy doctor`` and confirm the Bash config parses with `risk: restricted` and the five default commands.
2. Start the agent and, as Creator, call ``shell_exec`` with `{ "command": "pwd" }`; confirm a JSON result with `exitCode: 0`.
3. Call ``shell_exec`` with `{ "command": "printf", "args": ["no"] }`; confirm the allowlist rejects it.
4. Inspect the runtime capability view as an agent or public peer; confirm neither Bash tool is exposed by default.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## Budgets

URL: https://auggy.dev/docs/augment-budgets/markdown
Status: Preview
Summary: Gate turns and record per-peer runtime usage with SQLite-backed caps.
Sections: Outcome, Install and configure, Use it, Runtime surfaces, Boundaries, Verify

# Budgets

Canonical: https://auggy.dev/docs/augment-budgets
Status: Preview
Package: auggy 0.5.0

Gate turns and record per-peer runtime usage with SQLite-backed caps.

## Outcome

**What it enables:** Admit or reject turns by trust level and track turn counts, priced spend, and anonymous request rates.

- **Status:** Preview
- **Availability:** Install with ``auggy augment add` budgets`; the generated database is `./data/budgets.db`.
- **Contributes:** `turn gate`, `context`, `admin`

Budgets runs before the model call, reserves an allowed turn in SQLite, then commits the provider cost after the response. Creator and internal turns bypass the store.

## Install and configure

1. Run ``auggy augment add` budgets` in the agent project and confirm the Preview prompt.
2. Review `augments/budgets/augment.yaml`; the database path is relative to the agent project.
3. Run ``auggy doctor``, then restart the agent after changing caps.

**augments/budgets/augment.yaml**

```yaml
type: budgets
config:
  dbPath: ./data/budgets.db
  caps:
    public:
      recognized:
        maxTurnsPerThread: 20
        maxTurnsPerDay: 50
        maxUsdPerDay: 1
      anonymous:
        maxTurnsPerThread: 5
  anonymousGlobalLimit: 30
  dailyBudgetUsd: 5
```

`caps.agent`, `caps.public.anonymous`, and `caps.public.recognized` accept `maxTurnsPerThread`, `maxTurnsPerDay`, and `maxUsdPerDay`. The creator tier is intentionally omitted because it bypasses budgets.

## Use it

Use a recognized-visitor cap for a support chat that should allow enough context to solve one issue but stop runaway conversations and spend.

**A bounded support-chat policy**

```yaml
type: budgets
config:
  dbPath: ./data/budgets.db
  caps:
    public:
      recognized:
        maxTurnsPerThread: 8
        maxTurnsPerDay: 24
        maxUsdPerDay: 0.50
  dailyBudgetUsd: 10
```

After restart, a recognized peer receives a budget preamble showing remaining turns and estimated spend. Once a cap is exceeded, the next turn is rejected before the engine call.

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| Turn gate | `prepare` evaluates thread, daily, anonymous-window, peer-dollar, and global-dollar caps; denial is `cap-denied` and makes no engine call. |
| Context | Capped peers receive a high-priority, turn-scoped BATS preamble with remaining turns, estimated spend, and bucketed guidance. |
| Cost commit | After a response, priced USD is written to ``peer_daily_costs`` and ``daily_global``; unpriced turns are counted separately. |
| Admin | Runtime admin info shows today's spend and peer breakdown; the daily cap can be adjusted or reset, with overrides persisted in `admin-overrides.json`. |
| SQLite | ``turn_reservations``, ``peer_daily_costs``, ``daily_global``, and ``anonymous_requests`` are created at `dbPath`. |

## Boundaries

| Area | Current boundary |
| --- | --- |
| Trust | Creator and null/internal turns bypass caps and do not write reservations. Agent and public peers are capped only when their trust-tier config exists; public splits into anonymous and recognized. |
| Persistence | SQLite is single-process and single-replica. No automatic purge runs unless `retentionDays` is set; pending reservations are swept after the cleanup window. |
| Deployment | Keep the database on durable storage and run one replica. Use provider-side quotas or hard spend caps for unattended deployment. |
| Limitations | Dollar caps are post-hoc soft caps and can overshoot by one turn. Unpriced provider responses do not add USD, though turn caps still apply. This is runtime guardrail accounting, not billing control. |

> **Warning: Plan for overshoot**
>
> A USD cap is checked against settled spend before admission and cost is known only after the model response. Keep provider-side hard limits in place when the dollar ceiling must be authoritative.

## Verify

1. Run ``auggy doctor`` and confirm `dbPath` and cap values parse.
2. Start the agent with a recognized peer and complete one turn; confirm the model context contains the BATS remaining-turn lines.
3. Set `maxTurnsPerThread: 2`, complete two turns in one thread, then send a third; confirm `status: rejected`, `errorClass: cap-denied`, and no model call for the third turn.
4. Inspect the SQLite file and confirm a reservation row plus the priced or unpriced cost record; do not expect creator turns to create rows.

## Related

- [Visitor Auth](https://auggy.dev/docs/augment-visitor-auth/markdown)
- [Turn Control](https://auggy.dev/docs/augment-turn-control/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
## Link

URL: https://auggy.dev/docs/augment-link/markdown
Status: Preview
Summary: Exchange authenticated text messages with configured A2A peers over a separate HTTP listener.
Sections: Outcome, Install and configure, Use it, Runtime surfaces, Boundaries, Verify

# Link

Canonical: https://auggy.dev/docs/augment-link
Status: Preview
Package: auggy 0.5.0

Exchange authenticated text messages with configured A2A peers over a separate HTTP listener.

## Outcome

**What it enables:** Give an agent authenticated, text-only A2A sends and inbound turns from named peer agents.

- **Status:** Preview
- **Availability:** Install with ``auggy augment add` link`; it adds `@auggy/link@^0.1.2` and defaults to port `8081`.
- **Contributes:** `tools`, `transport`

Link is separate from webTransport: it speaks A2A JSON-RPC over its own HTTP listener while webTransport continues to serve the agent's browser-facing surfaces.

## Install and configure

1. Run ``auggy augment add` link` in the agent project and confirm the Preview prompt.
2. Set the agent-card environment variables and review `augments/link/augment.yaml`.
3. Run ``auggy doctor``, then `bun install` if the package install was skipped; restart after changing peers or port.

**augments/link/augment.yaml**

```yaml
type: link
config:
  port: 8081
  dbPath: ./data/link.db
  agentCard:
    id: "${AUGGY_AGENT_ID}"
    name: "${AUGGY_AGENT_NAME}"
    description: Auggy link endpoint
    endpointUrl: "${AUGGY_LINK_PUBLIC_URL}"
  peers: {}
```

**.env**

```env
AUGGY_AGENT_ID=00000000-0000-0000-0000-000000000001
AUGGY_AGENT_NAME=front-door
AUGGY_LINK_PUBLIC_URL=https://front-door.example.org
```

The install also copies `skills/link/SKILL.md` and adds `@auggy/link` to the agent package. Bearers belong in environment-backed config, not in a shared registry.

## Use it

Configure one research peer with separate outbound and inbound bearers, then let the agent discover it before delegating a question.

**Inline peer configuration**

```yaml
type: link
config:
  port: 8081
  dbPath: ./data/link.db
  agentCard:
    id: "${AUGGY_AGENT_ID}"
    name: "${AUGGY_AGENT_NAME}"
    description: Front-door agent
    endpointUrl: "${AUGGY_LINK_PUBLIC_URL}"
  peers:
    researcher:
      url: https://researcher.example.org
      bearer: "${RESEARCHER_BEARER}"
      participantId: 00000000-0000-0000-0000-000000000002
      inboundBearer: "${RESEARCHER_INBOUND_BEARER}"
      inboundBearerId: researcher-front-door
      purpose: Research specialist
      examples:
        - What is the current state of test-time compute?
```

**Model tool inputs**

```json
{
  "link_list": {},
  "link_send": {
    "to": "researcher",
    "text": "Summarize the latest evidence on test-time compute."
  }
}
```

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| HTTP listener | Own **Bun**.serve port `8081` by default; separate from webTransport. |
| GET /health | Link service health endpoint. |
| GET /.well-known/agent.json | Serves the configured agent card. |
| POST /a2a/v1 | Bearer-authenticated A2A JSON-RPC inbound messages translated into **Auggy** turns. |
| GET /a2a/v1/stream | Present but returns the current `501` stream stub. |
| `link_list` | Returns configured peer names plus optional purpose and examples. |
| `link_send` | Sends text to a named peer; returns synchronous reply text or `{ ok: true, outcome: "task", taskId }`. |
| Context and storage | Adds peer names to the turn preamble; `link.db` backs the link task store. |

## Boundaries

| Area | Current boundary |
| --- | --- |
| Trust | A configured inbound bearer grants that peer admission as `agent` trust. Bearer possession is an authority boundary; public or anonymous traffic is rejected before the turn. |
| Persistence | `link.db` is used by the link task store. Peer-source cache is in memory; inline peers remain in config. Rotate bearers separately from peer names or URLs. |
| Deployment | Expose and route the separate link port. Peer and registry URLs require HTTPS by default; `LINK_ALLOW_PLAINTEXT=1` is the localhost-development override. |
| Limitations | Traffic is text-only. Synchronous replies are supported; no model tool follows asynchronous task IDs, so a returned `taskId` has no built-in polling or completion workflow. The stream endpoint is a `501` stub. |

> **Warning: Treat bearers as trust grants**
>
> Link bearers grant agent trust today. Do not use this listener for public or reduced-privilege peers, and do not put bearer values in a registry response.

## Verify

1. Run ``auggy doctor`` and confirm the agent card, `dbPath`, peer fields, and port parse.
2. Start the agent and run `curl http://127.0.0.1:8081/health`; confirm the link listener responds independently of webTransport.
3. Run `curl http://127.0.0.1:8081/.well-known/agent.json`; confirm the response matches the configured agent card.
4. As Creator, call ``link_list``, then ``link_send`` to the configured peer; confirm the peer name resolves and a synchronous text response is returned.
5. Send one inbound request with the configured bearer and confirm the resulting peer identity is `agent` trust; retry without the bearer and confirm HTTP 401.

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Transports](https://auggy.dev/docs/transports/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Budgets](https://auggy.dev/docs/augment-budgets/markdown)
## Console

URL: https://auggy.dev/docs/console/markdown
Status: Published
Summary: Test the running agent and inspect its capabilities, caller contexts, tool calls, and live runtime configuration.
Sections: URLs, Test caller identity, Inspect tool calls, Inspect the running agent, Production access

# Console

Canonical: https://auggy.dev/docs/console
Status: Published
Package: auggy 0.5.0

Test the running agent and inspect its capabilities, caller contexts, tool calls, and live runtime configuration.

## URLs

**Local console URLs**

```
Chat:          http://localhost:8080/console/chat
Capabilities:  http://localhost:8080/console/capabilities
Console:       http://localhost:8080/console
Health:        http://localhost:8080/health
Home:          http://localhost:8080/
```

Every agent serves its own console. There is no separate GUI to install or run.

## Test caller identity

Switch between creator, anonymous visitor, and verified visitor to confirm that each caller sees the expected tools and behavior.

![Auggy console chat with creator, anonymous, and verified visitor identity controls](https://auggy.dev/brand/console-auth-context.webp)

_Preview the same agent under different caller identities._

## Inspect tool calls

Expand a tool call to inspect its validated arguments, result, category, and completion state. The console does not yet provide a complete model-call trace inspector.

![Auggy console with an expanded memory_write tool call showing arguments and result](https://auggy.dev/brand/console-tool-call-inspect.webp)

_An expanded `memory_write` call with its arguments and result._

## Inspect the running agent

Use the capabilities and runtime panels to confirm what the agent actually loaded. This is the fastest way to catch a missing augment, unexpected caller posture, or configuration mismatch before testing model behavior.

| Surface | What it answers |
| --- | --- |
| Capabilities | Which tools and augments are available to the selected caller. |
| Runtime configuration | Which engine, model, transport, and project configuration the process loaded. |
| Health | Whether the process and augment lifecycle completed successfully. |
| Tool results | Which validated operation ran, with what arguments, and how it completed. |

> **Note: Optional app integration has its own guide**
>
> The integration panel can also expose preview route manifests and application setup data. That surface is documented under Advanced Preview and is not part of the normal Console workflow.

## Production access

- Protect creator console access with transport auth and production policy.
- Do not use console magic links on **Railway** unless allowConsoleInProduction is explicitly set.
- Use the console for operator-facing diagnostics, not as the public visitor surface.

## Related

- [Run an agent](https://auggy.dev/docs/quickstart/markdown)
- [Logs and recovery](https://auggy.dev/docs/logs-and-recovery/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
## Logs and recovery

URL: https://auggy.dev/docs/logs-and-recovery/markdown
Status: Published
Summary: Use Auggy and Railway diagnostics to recover from deploy, boot, route, and runtime failures.
Sections: Commands, When to use logs

# Logs and recovery

Canonical: https://auggy.dev/docs/logs-and-recovery
Status: Published
Package: auggy 0.5.0

Use **Auggy** and **Railway** diagnostics to recover from deploy, boot, route, and runtime failures.

## Commands

**Diagnostics**

```bash
auggy doctor
auggy logs
auggy deploy
auggy deploy --yes
```

`auggy doctor` checks the local project configuration and environment. `auggy logs` reads the saved **Railway** cloud record, links a temporary **Railway** workspace to the saved project/service, and streams **Railway** logs.

## When to use logs

- Deploy health verification times out.
- **Railway** reports a crash loop.
- A route is failing after a schema, auth, or env change.
- An augment fails boot validation.
- You changed .env or agent.yaml and need startup diagnostics.

## Related

- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
- [Console](https://auggy.dev/docs/console/markdown)
## Security

URL: https://auggy.dev/docs/security/markdown
Status: Published
Summary: Auggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.
Sections: What the runtime decides, Prompt injection threat model, Secrets and data at rest, Report a vulnerability, Scope and supported versions

# Security

Canonical: https://auggy.dev/docs/security
Status: Published
Package: auggy 0.5.0

**Auggy**'s security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.

## What the runtime decides

The runtime, not the model, decides caller identity, authorization, trust level, and which tools are available.

- Peer trust is structural. Transports assign creator, agent, or public at the boundary; public callers are anonymous or recognized.
- The capability table filters tools before the engine sees them. A tool outside the current trust level cannot be called.
- Route and tool requires rules check scopes and grants before any handler or execute function runs.
- Context carries provenance (operator, system, agent, agent-derived, peer-derived), so peer-supplied text cannot masquerade as operator policy.
- Secrets stay in .env or provider-owned stores, never in prompt-visible files.

## Prompt injection threat model

Injected text can always influence what the model says. The security question is what it can make the runtime do. **Auggy** treats injection as a vulnerability when it crosses an explicit security boundary.

| Injection outcome | Treated as |
| --- | --- |
| Escalates a peer's trust level | Vulnerability. In scope. |
| Exfiltrates creator-only memory | Vulnerability. In scope. |
| Evades the capability table | Vulnerability. In scope. |
| Changes tone or wording without crossing a boundary | Model-quality issue. Out of scope. |

## Secrets and data at rest

- Keep provider keys and signing secrets in .env or a provider-owned secret store.
- Persistent runtime state, including visitor memory, auth records, and AgentMail ledgers/review queues, lives in hardened SQLite stores. On **Railway** core paths resolve directly under /app/data and AgentMail is isolated under /app/data/agent-mail/<augment-name>.
- identity.md, learned-behaviors.md, skills, and knowledge sources are prompt-visible. Never put secrets in them.

## Report a vulnerability

Do not open a public issue for a security vulnerability. Email [hello@looselyorganized.xyz](mailto:hello@looselyorganized.xyz) with a description of the vulnerability and its impact, the **Auggy** and **Bun** versions, and a reproduction such as proof-of-concept code or step-by-step instructions. Invited source collaborators can also use **GitHub** private vulnerability reporting.

| Stage | Target |
| --- | --- |
| Acknowledgement | Within 3 business days. |
| Initial triage and severity | Within 7 business days. |
| Fix or mitigation | Prioritized by severity ahead of feature work. |
| Public disclosure | Coordinated, typically within 14 days of fix availability. |

> **Note: Best effort, not an SLA**
>
> **Auggy** is a small project. These targets are best-effort response commitments rather than a contract. Reporters who follow this policy are credited in the advisory and changelog unless they request anonymity.

## Scope and supported versions

- In scope: the **Auggy** runtime (kernel, augments, engines, transports, memory), the CLI and launchd integration, and docs that claim a security property the implementation does not have.
- Out of scope: vulnerabilities in upstream dependencies (report those upstream), prompt injection that does not bypass an **Auggy** boundary, issues requiring physical access to the operator's machine, and operator-authored identity files.

Only the latest published minor release receives security patches. **Auggy** is pre-1.0 and breaking changes between minor versions are possible, so pin to an exact version in production until 1.0.

## Related

- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)
## Optional app integration

URL: https://auggy.dev/docs/engineering-patterns/markdown
Status: Preview
Summary: Advanced preview routes, generated clients, webhooks, and delegated authorization for agents that need a small deterministic application boundary.
Sections: Start with the agent path, Three compact patterns, Implementation shape, Choose the right depth

# Optional app integration

Canonical: https://auggy.dev/docs/engineering-patterns
Status: Preview
Package: auggy 0.5.0

Advanced preview routes, generated clients, webhooks, and delegated authorization for agents that need a small deterministic application boundary.

## Start with the agent path

> **Note: Optional, not the default scaffold**
>
> Most **Auggy** projects do not need routes or generated clients. Start with tools. Add this surface only when existing software genuinely needs a deterministic HTTP entry point beside the agent.

Software calls a route when the operation is known. The agent calls a tool when conversation or investigation must determine the operation. Both call one domain function.

> **Note: These are patterns, not built-ins**
>
> Your application still owns infrastructure, authorization records, and domain policy. Use an augment when a route and tool would otherwise duplicate those rules.

## Three compact patterns

### Manage feature flags

- **Software path:** An admin console calls PATCH /flags/:key with an explicit rollout percentage, audience, and change reason.
- **Agent path:** During an incident, an engineer asks **Auggy** to compare telemetry and propose reducing new-checkout for a region. The model gathers confirmation before calling the tool.
- **Shared operation:** `updateFeatureFlag()` verifies the flag, environment, rollout bounds, audience, authorization, change window, and audit metadata before writing.
- **Why Auggy:** The admin UI and incident workflow use the same rollout policy.

### Provision preview environments

- **Software path:** A **GitHub** webhook calls POST /environments when a pull request receives the preview label.
- **Agent path:** An engineer asks for PR 1842 with sanitized production data, a specific region, and a QA notification. The model turns those constraints into typed input.
- **Shared operation:** `provisionEnvironment()` selects approved infrastructure, applies data policy, records owner and pull request, sets expiration, and submits one idempotent provisioning job.
- **Why Auggy:** Conversation gathers options without creating a second provisioning system.

### Run a data backfill

- **Software path:** An operations dashboard calls POST /backfills after a dry run has identified the job type, tenant scope, affected rows, and rollback plan.
- **Agent path:** An engineer asks **Auggy** to find customers missing invoice totals, estimate impact, and prepare the smallest safe backfill for approval.
- **Shared operation:** `createBackfill()` accepts a reviewed plan, validates the registered job definition, tenant scope, dry-run evidence, concurrency ceiling, approval, idempotency, and rollback metadata.
- **Why Auggy:** Investigation stays flexible; admission stays inside the registered job system.

## Implementation shape

**Route and tool faces**

```
PATCH /flags/:key        + update_feature_flag
  -> updateFeatureFlag()

POST /environments        + provision_preview_environment
  -> provisionEnvironment()

POST /backfills           + prepare_backfill
  -> createBackfill()
```

The plus sign does not mean both paths execute. Routes bypass inference; tools run through the model and tool gates. Each still declares its own auth and rate limits.

## Choose the right depth

| Situation | Recommended shape |
| --- | --- |
| Known operation from CI, UI, or webhook | Call the route directly. |
| Missing fields or ambiguous intent | Let the model gather context, then call a typed tool. |
| Read-only investigation | Use narrow read tools; do not expose the write operation yet. |
| Consequential write | Require application authorization or approval in the shared domain operation. |
| No software caller yet | Start with a tool; add a route when software needs the capability. |

## Related

- [Add HTTP routes](https://auggy.dev/docs/add-http-routes/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Webhooks](https://auggy.dev/docs/webhooks/markdown)
- [defineRoute](https://auggy.dev/docs/define-route/markdown)
## Add HTTP routes

URL: https://auggy.dev/docs/add-http-routes/markdown
Status: Preview
Summary: Advanced preview: expose focused HTTP behavior for frontends, webhooks, and server integrations without running a model turn.
Sections: When to add a route, Current route surface, Route example, Route classes

# Add HTTP routes

Canonical: https://auggy.dev/docs/add-http-routes
Status: Preview
Package: auggy 0.5.0

Advanced preview: expose focused HTTP behavior for frontends, webhooks, and server integrations without running a model turn.

## When to add a route

> **Note: Optional advanced preview**
>
> A normal **Auggy** project does not need HTTP routes. Add one only when software already knows the exact operation it needs; use a tool when the model should mediate the operation during a turn.

- A browser, mobile app, server job, webhook, or outside service needs to call the capability directly.
- The behavior should be typed, repeatable, auditable, fast, or state-changing.
- A generated client should call the capability without hand-writing paths and auth headers.
- A chat-first flow needs a route-backed UI component to complete a structured action.

## Current route surface

- GET and POST routes.
- Exact paths and full-segment path params such as /orders/:id.
- Route groups, path params, query parsing, JSON body parsing, and response helpers.
- Zod schemas for params, query, body, and successful JSON responses.
- auth: none, bearer, creator, visitor.optional, visitor.required, or agent.required.
- Per-route body caps, timeouts, and rate limits.
- Route manifests, --json, --openapi, and generated TypeScript clients through `auggy routes`.
- Webhook signature policy metadata, with runtime Stripe and Svix verification.

## Route example

**Typed route**

```ts
import { defineRoute, json } from "auggy";
import { z } from "zod";

const SearchQuery = z.object({
  q: z.string().min(1),
});

export const routes = [
  defineRoute.get("/services/search", {
    auth: "none",
    query: SearchQuery,
    response: z.object({
      services: z.array(z.object({ id: z.string(), name: z.string() })),
    }),
    handler: async ({ query }) => {
      const services = await searchServices(query.q);
      return json({ services });
    },
  }),
];
```

## Route classes

| Route class | Examples | Typical auth |
| --- | --- | --- |
| Public discovery | GET /catalog/search, GET /services | none or visitor.optional |
| Lead and intake | POST /leads/create, POST /support/intake | none or visitor.optional |
| Draft state | POST /orders/draft, POST /appointments/hold | visitor.optional or visitor.required |
| Final handoff | POST /checkout/create, POST /bookings/:id/confirm | visitor.required |
| Account lookup | GET /orders/:id, GET /tickets/:id/status | visitor.required |
| Webhooks | POST /webhooks/stripe or /webhooks/agentmail | Stripe/Svix signature policy or handler-verified provider auth |
| Operator actions | POST /admin/reindex, POST /catalog/sync | bearer or creator |

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [defineRoute](https://auggy.dev/docs/define-route/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
## Connect an application

URL: https://auggy.dev/docs/connect-application/markdown
Status: Preview
Summary: Advanced preview: generate a typed route client and call an augment route from a Next.js application.
Sections: What you will connect, Inspect the running route, Generate the browser client, Configure one client, Call the capability, Allow the application origin, Verify the integration, When the capability is protected

# Connect an application

Canonical: https://auggy.dev/docs/connect-application
Status: Preview
Package: auggy 0.5.0

Advanced preview: generate a typed route client and call an augment route from a Next.js application.

## What you will connect

> **Note: Advanced preview**
>
> This integration is optional. **Auggy** does not replace the application's frontend, database, auth system, or primary backend, and generated client helpers may change before 1.0.

The agent and application remain separate projects. The application calls the GET /services route built in the previous guide through a generated TypeScript client.

**Application path**

```
Next.js filter UI
  -> generated Auggy client
  -> GET /services
  -> catalog augment
  -> searchServices()
```

**Separate repositories**

```
storefront/
  src/lib/auggy-client.ts   # generated
  src/lib/auggy.ts          # application-owned config

my-agent/
  agent.yaml
  augments/catalog/
```

## Inspect the running route

1. Run the agent and open `/console/integrations`.
2. Confirm GET /services appears under App routes with auth none.
3. Confirm the application origin appears under `CORS` origins before testing from a browser.

## Generate the browser client

**Run from the agent project**

```bash
auggy routes my-agent --client ts --target browser \
  --out ../storefront/src/lib/auggy-client.ts
```

The generated file contains typed methods for routes that are safe for browser callers. Regenerate it when a route path, method, schema, or auth mode changes.

## Configure one client

**storefront/.env.local**

```env
NEXT_PUBLIC_AUGGY_BASE_URL=http://localhost:8080
```

**storefront/src/lib/auggy.ts**

```ts
import { createAuggyClient } from "./auggy-client";

export const auggy = createAuggyClient({
  baseUrl: process.env.NEXT_PUBLIC_AUGGY_BASE_URL!,
});
```

> **Warning: The browser URL is public**
>
> Never put creator bearer tokens, signing secrets, provider keys, or agent credentials in NEXT_PUBLIC_ variables.

## Call the capability

**storefront/src/components/service-search.tsx**

```ts
"use client";

import { useState, type FormEvent } from "react";
import { auggy } from "@/lib/auggy";

type Service = {
  id: string;
  name: string;
  summary: string;
  startingAtUsd: number;
};

export function ServiceSearch() {
  const [need, setNeed] = useState("");
  const [services, setServices] = useState<Service[]>([]);
  const [error, setError] = useState<string>();

  async function search(event: FormEvent) {
    event.preventDefault();
    setError(undefined);

    const result = await auggy.get("/services", {
      query: { need },
    });

    if (!result.ok) {
      setError(`Search failed (${result.status})`);
      return;
    }

    setServices(result.data.services);
  }

  return (
    <form onSubmit={search}>
      <input value={need} onChange={(event) => setNeed(event.target.value)} />
      <button type="submit">Search</button>
      {error ? <p>{error}</p> : null}
      <ul>
        {services.map((service) => <li key={service.id}>{service.name}</li>)}
      </ul>
    </form>
  );
}
```

## Allow the application origin

**my-agent/augments/webTransport/augment.yaml**

```yaml
type: webTransport
config:
  port: 8080
  cors:
    origins:
      - http://localhost:3000
```

Restart the agent after changing transport configuration, then confirm the resolved origin in `/console/integrations`.

## Verify the integration

1. Start the agent on port 8080 and the Next.js application on port 3000.
2. Search for gift in the application and confirm Curated Gifting renders.
3. Ask the agent for a gift service under $200 and confirm it reaches the same result through `service_search`.
4. Change the route schema, regenerate the client, and confirm TypeScript reflects the new contract.

## When the capability is protected

| Need | Next step |
| --- | --- |
| Existing app login should authorize **Auggy** | [Add delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown) |
| Production hosting | [Deploy and verify](https://auggy.dev/docs/deploy/markdown) |

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## Delegated authorization

URL: https://auggy.dev/docs/delegated-authorization/markdown
Status: Preview
Summary: Advanced preview: bridge an existing app login into Auggy with short-lived assertions and route/tool requires rules.
Sections: Boundary, Flow, Mint assertions, Route and tool requires

# Delegated authorization

Canonical: https://auggy.dev/docs/delegated-authorization
Status: Preview
Package: auggy 0.5.0

Advanced preview: bridge an existing app login into **Auggy** with short-lived assertions and route/tool requires rules.

## Boundary

> **Note: Advanced preview**
>
> Use this only when an existing application must authorize optional **Auggy** routes or protected tools. Keep the application's identity provider and authorization records as the source of truth.

Delegated authorization lets a **Supabase**, **Clerk**, Auth0-style, or custom app session call visitor.required routes and protected tools without making **Auggy** a general auth provider.

- The app verifies the user session and decides what the user may do.
- The app mints a compact, short-lived **Auggy** assertion.
- **Auggy** verifies the signature, audience, provider, key ID, TTL, and replay protection.
- **Auggy** enforces route-local and tool-local requires rules against assertion scopes and grants.
- Roles can travel as context, but roles do not satisfy authorization requirements.

> **Note: Team/internal users today**
>
> Staff and customers use public recognized identity with app-minted scopes and grants. People operating the **Auggy** instance use creator access. Per-operator console permissions are future work.

## Flow

1. Browser: Has a normal app login session.
2. Browser: Asks the app backend for an **Auggy** auth assertion.
3. App backend: Verifies the session with its trusted provider.
4. App backend: Derives minimal scopes and resource grants.
5. App backend: Signs a short-lived assertion.
6. Browser: Calls **Auggy** with x-auggy-auth-assertion.
7. Auggy: Resolves public recognized context and enforces route/tool requires before work runs.

## Mint assertions

**Server-side assertion helper**

```ts
import { createExternalAuthAssertion } from "auggy";

export async function mintAuggyAssertionForUser(user: {
  id: string;
  email?: string;
  orgId?: string;
  roles: string[];
}) {
  const grants = await delegatedGrantsForUser(user);

  return createExternalAuthAssertion({
    secret: process.env.AUGGY_EXTERNAL_AUTH_SECRET!,
    keyId: "2026-07",
    audience: "storefront-agent",
    provider: "custom",
    subject: user.id,
    ttlSeconds: 60,
    email: user.email,
    emailVerified: true,
    orgId: user.orgId,
    roles: user.roles,
    scopes: ["orders.read"],
    grants,
    authzVersion: "orders-v1",
    jti: crypto.randomUUID(),
  });
}
```

> **Warning: Server only**
>
> Never put AUGGY_EXTERNAL_AUTH_SECRET in browser code. The generated browser client can forward an assertion through authAssertion, but the app backend must create it.

## Route and tool requires

**Route requirement**

```ts
defineRoute.post("/orders/:id/refund", {
  auth: "visitor.required",
  params: z.object({ id: z.string() }),
  body: z.object({ reason: z.string() }),
  requires: { action: "refund.issue", resource: { param: "id" } },
  handler: ({ params }) => json({ refundId: "refund_123", orderId: params.id }),
});
```

**Tool requirement**

```ts
defineTool({
  name: "refund_order",
  description: "Refund a customer order.",
  category: "commerce",
  input: z.object({
    orderId: z.string(),
    reason: z.string(),
  }),
  requires: {
    action: "refund.issue",
    resource: { input: "orderId" },
  },
  execute: async ({ orderId }) => "refund-started:" + orderId,
});
```

## Related

- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
## Webhooks

URL: https://auggy.dev/docs/webhooks/markdown
Status: Preview
Summary: Advanced preview: handle provider callbacks through focused augment routes with deterministic signature checks.
Sections: Purpose, Current support, Pattern

# Webhooks

Canonical: https://auggy.dev/docs/webhooks
Status: Preview
Package: auggy 0.5.0

Advanced preview: handle provider callbacks through focused augment routes with deterministic signature checks.

## Purpose

> **Note: Advanced preview**
>
> Webhook routes are an optional integration surface. Existing application webhook handlers can continue to own provider callbacks and invoke narrow agent tools or notifications only when needed.

Webhooks are provider infrastructure, not chat turns. Verify and handle routine callbacks in code; notify the operator when they fail.

## Current support

- Webhook signature policy metadata on route definitions.
- Runtime Stripe and Svix signature verification before the handler runs.
- Webhook policy routes are omitted from browser generated clients.
- Svix verification checks the raw body, signature envelope, delivery ID, and timestamp age before the handler runs.

## Pattern

**Provider callback route**

```ts
import { defineRoute, webhook } from "auggy";

defineRoute.post("/webhooks/stripe", {
  auth: "none",
  maxBodyBytes: 64_000,
  policy: webhook.signature("stripe", { secretEnv: "STRIPE_WEBHOOK_SECRET" }),
  handler: async ({ webhook: verified }) => {
    await applyBillingEvent(verified?.event);
    return new Response("ok");
  },
});
```

For a Svix-signed provider, use `webhook.signature("svix", { secretEnv: "PROVIDER_WEBHOOK_SECRET" })`. AgentMail inbound mounts this policy at `/webhooks/agentmail` and then applies its own inbox, sender, classification, dedup, and turn-admission rules.

> **Warning: Do not model-verify webhooks**
>
> Verify provider signatures in code. Do not ask the model whether a callback is valid.

## Related

- [Add HTTP routes](https://auggy.dev/docs/add-http-routes/markdown)
- [Delegated authorization](https://auggy.dev/docs/delegated-authorization/markdown)
- [Logs and recovery](https://auggy.dev/docs/logs-and-recovery/markdown)
## defineRoute

URL: https://auggy.dev/docs/define-route/markdown
Status: Preview
Summary: Advanced preview: define focused HTTP routes with typed schemas, auth modes, and generated-client support.
Sections: Shape, Options, Auth modes

# defineRoute

Canonical: https://auggy.dev/docs/define-route
Status: Preview
Package: auggy 0.5.0

Advanced preview: define focused HTTP routes with typed schemas, auth modes, and generated-client support.

## Shape

> **Note: Optional app-integration API**
>
> defineRoute is not required to build an **Auggy** agent. Use it for a focused deterministic integration, not as a replacement for a general application backend.

**Route definition**

```ts
defineRoute.post("/orders/:id/refund", {
  auth: "visitor.required",
  params: z.object({ id: z.string() }),
  body: z.object({ reason: z.string() }),
  maxBodyBytes: 8192,
  rateLimit: { maxPerMinute: 5 },
  requires: { action: "refund.issue", resource: { param: "id" } },
  response: z.object({ refundId: z.string(), orderId: z.string() }),
  handler: async ({ params, body }) => {
    return json(await refundOrder(params.id, body.reason));
  },
});
```

defineRoute.get and defineRoute.post are the supported methods. Paths take exact segments and full-segment params such as /orders/:id.

## Options

| Option | Use |
| --- | --- |
| auth | One of none, bearer, creator, visitor.optional, visitor.required, or agent.required. |
| params, query, body | Zod schemas; parsed and validated before the handler runs. |
| response | Zod schema for the success JSON body; types the generated client's data. |
| maxBodyBytes | Per-route request body cap. |
| rateLimit | { maxPerMinute } per-route rate limit. |
| timeoutMs | Per-route handler timeout. |
| policy | Webhook policy metadata, such as webhook.signature("stripe", { secretEnv }) or webhook.signature("svix", { secretEnv }). |
| requires | Delegated authorization rule: { action, resource: { param } }. |
| handler | Receives parsed { params, query, body, request } and returns a Response; `json()` is the standard helper. |

## Auth modes

| Mode | Use |
| --- | --- |
| none | Public routes. |
| bearer | Trusted server or operator callers with bearer credentials. |
| creator | Creator-only maintenance and back-office actions. |
| visitor.optional | Public routes that can enrich behavior when a visitor token is present. |
| visitor.required | Private visitor routes that require verified visitor identity. |
| agent.required | Admitted agent callers. |

## Related

- [Add HTTP routes](https://auggy.dev/docs/add-http-routes/markdown)
- [Connect an application](https://auggy.dev/docs/connect-application/markdown)
- [Webhooks](https://auggy.dev/docs/webhooks/markdown)
## CLI reference

URL: https://auggy.dev/docs/cli-reference/markdown
Status: Published
Summary: Common Auggy CLI commands for creating, extending, and operating agents.
Sections: Commands, Common flows, Advanced preview commands

# CLI reference

Canonical: https://auggy.dev/docs/cli-reference
Status: Published
Package: auggy 0.5.0

Common **Auggy** CLI commands for creating, extending, and operating agents.

## Commands

| Command | Use |
| --- | --- |
| `auggy create <name>` | Create a standalone agent project. |
| `auggy run` | Run the local agent server. |
| `auggy augment list` | List available built-in and custom augments. |
| `auggy augment add <name>` | Add an augment config, dependencies, and bundled skill when available. |
| `auggy augment create <name>` | Create a custom augment scaffold. |
| `auggy skill create <name>` | Create a skill folder. |
| `auggy skill add <name>` | Refresh a bundled starter or augment skill folder, including auggy and layeredMemory. |
| `auggy skill list` | List skills installed in the current agent. |
| `auggy deploy` | Deploy the current agent to **Railway**. |
| `auggy logs` | Stream logs for the saved **Railway** target. |

A machine-readable version of the CLI and factory API surface, with signatures and per-symbol release status, is served at /api-reference.json.

## Common flows

**Create, extend, inspect, deploy**

```bash
auggy create my-agent
cd my-agent
auggy augment add knowledge layeredMemory
auggy augment create support
auggy doctor
auggy deploy
```

## Advanced preview commands

> **Warning: Optional app integration**
>
> These commands inspect and generate artifacts for preview augment routes. A normal tool-focused agent does not need them.

| Command | Use |
| --- | --- |
| `auggy routes [name]` | Inspect optional deterministic augment routes. |
| `auggy routes [name] --json` | Emit route manifest JSON. |
| `auggy routes [name] --openapi` | Emit an OpenAPI 3.1 document for the agent's routes. |
| `auggy routes [name] --client ts` | Generate a TypeScript route client. |

## Related

- [Run an agent](https://auggy.dev/docs/quickstart/markdown)
- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)
## agent.yaml

URL: https://auggy.dev/docs/agent-yaml/markdown
Status: Published
Summary: Configure identity, engine, and enabled augment order for an agent project.
Sections: Role, Rules

# agent.yaml

Canonical: https://auggy.dev/docs/agent-yaml
Status: Published
Package: auggy 0.5.0

Configure identity, engine, and enabled augment order for an agent project.

## Role

agent.yaml is the runtime source of truth for an agent project. It declares identity, model-provider configuration, settings, and enabled augment order.

**Scaffolded shape**

```yaml
name: my-agent
displayName: My Agent
purpose: Help visitors with product and support workflows.
creator:
  displayName: Operator
identity: ./identity.md

engine:
  provider: anthropic
  model: claude-sonnet-4-6
  maxContextTokens: 200000
  maxTokens: 4096
  # reasoningEffort: medium
  # costOverride:
  #   inputUsdPerMtok: 3
  #   outputUsdPerMtok: 15

settings:
  compactionStrategy: truncate
  maxInferenceLoops: 10

augments:
  - fileMemory
  - filesystem
  - webTransport
  - webFetch
  - turnControl
  - knowledge
```

## Rules

- Keep secrets in .env, not agent.yaml.
- Use engine.provider and engine.model for model selection; use maxContextTokens, maxTokens, and provider-specific fields for runtime behavior.
- Treat augment order as part of runtime behavior.
- Use augment-specific config in augments/<id>/augment.yaml.

## Related

- [defineAugment](https://auggy.dev/docs/define-augment/markdown)
## defineAugment

URL: https://auggy.dev/docs/define-augment/markdown
Status: Published
Summary: Define a runtime capability that contributes tools, context, memory, transports, lifecycle, or policy to an agent.
Sections: Shape, Options, Ownership

# defineAugment

Canonical: https://auggy.dev/docs/define-augment
Status: Published
Package: auggy 0.5.0

Define a runtime capability that contributes tools, context, memory, transports, lifecycle, or policy to an agent.

## Shape

**Minimal custom augment**

```ts
import { defineAugment } from "auggy";

export default function customAugment() {
  return defineAugment({
    name: "custom",
    type: "custom",
    tools: [],
  });
}
```

**Auggy** infers the augment's runtime surfaces from concrete fields such as tools, httpRoutes, context, transport, memory, and lifecycle hooks. There is no separate capabilities declaration.

## Options

| Option | Use |
| --- | --- |
| name | Unique augment identifier within the agent. |
| type | custom for project-specific augments; built-ins use their catalog type. |
| tools | defineTool entries this augment exposes to the model. |
| httpRoutes | Optional advanced preview defineRoute entries served beside /agent/run. |
| context | Async function returning ContextBlock entries for the turn. |

## Ownership

- Use one augment per domain capability, not one augment per function.
- Keep related tools, schemas, skills, integration code, and policy close together.
- Add optional routes only when software needs a deterministic entry point into this capability.
- Use lifecycle hooks for boot validation and cleanup.
- Use config files for operator-owned settings and env references.

## Related

- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [defineRoute](https://auggy.dev/docs/define-route/markdown)
- [defineTool](https://auggy.dev/docs/define-tool/markdown)
## defineTool

URL: https://auggy.dev/docs/define-tool/markdown
Status: Published
Summary: Define a typed model-callable function with validation and optional authorization requirements.
Sections: Shape, Options, Guidance

# defineTool

Canonical: https://auggy.dev/docs/define-tool
Status: Published
Package: auggy 0.5.0

Define a typed model-callable function with validation and optional authorization requirements.

## Shape

**Tool definition**

```ts
defineTool({
  name: "save_lead",
  description: "Save a lead for creator follow-up.",
  category: "business",
  input: z.object({
    email: z.string().email(),
    need: z.string(),
  }),
  execute: async (input) => JSON.stringify({ lead: await saveLead(input) }),
});
```

## Options

| Option | Use |
| --- | --- |
| name | Tool identifier the model calls; imperative or domain terms work best. |
| description | What the tool does and when to use it; the model selects tools from this. |
| category | Grouping label such as business or commerce. |
| input | Zod schema that validates model-provided input before execute runs. |
| execute | Async function receiving validated input; returns a string, usually JSON. |
| requires | Optional advanced preview delegated authorization rule: { action, resource: { input } }. |

## Guidance

- Use names that describe the operation in imperative or domain terms.
- Keep descriptions specific enough for tool selection.
- Keep input schemas narrow and explicit.
- Use skills for workflow teaching that does not fit in the tool description.
- Use the preview requires surface only when app-owned delegated authorization should gate execution.

## Related

- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [defineAugment](https://auggy.dev/docs/define-augment/markdown)
## Auggy Changelog

URL: https://auggy.dev/docs/changelog/markdown
Status: Published
Summary: Latest published runtime and CLI updates.
Sections: Source, Tagged releases, How to read this

# Auggy Changelog

Canonical: https://auggy.dev/docs/changelog
Status: Published
Package: auggy 0.5.0

Latest published runtime and CLI updates.

## Source

This changelog is summarized from tagged Git history in ../augment-1 through v0.5.0, released on July 7, 2026. It groups related commits into product-facing changes instead of listing every individual commit.

## Tagged releases

| Version | Date | Summary |
| --- | --- | --- |
| v0.5.0 | July 7, 2026 | Runtime public preview: focused turn kernel, composable augments, typed tools, project-local skills, Console, stable memory and integration augments, and **Railway** deployment. Optional routes, generated clients, and delegated application authorization remain advanced preview surfaces. |
| v0.4.4 | May 26, 2026 | Bundled Link skill teaching, peer directory registry support, filesystem-as-truth storage layout, auto-mounted skills, layeredMemory opt-in configuration, and create-flow cleanup. |
| v0.4.3 | May 19, 2026 | Added Ollama remote support and bearer auth in the create flow. |
| v0.4.2 | May 19, 2026 | Added Ollama to the create-flow model provider picker. |
| v0.4.1 | May 19, 2026 | Hotfixed an npm boot crash and split @auggy/evals. |
| v0.4.0 | May 19, 2026 | Added the GET/HEAD info endpoint, native Ollama adapter, first-party admin module, per-augment adminInfo/admin actions, provider package split, per-agent installs, and release hardening. |
| v0.3.1 | May 12, 2026 | First CI-driven feature release with **Railway** deploy CLI, npm publish workflow, layered-memory integration evals, robust JSON extraction, and codified release process. |
| v0.3.0 | May 12, 2026 | Name-claim publish backfill over a large feature span: skills augment separation, link augment, visitorAuth hardening, notify and Telegram work, AG-UI chat GUI, turnControl, agent registry, and security eval gates. |
| v0.2.0 | April 28, 2026 | Completed the visitor economics slice: creator/agent/public trust model, turn-gate budget contract, budgets augment, layeredMemory, visitor tokens, cost/pricing traces, and trust-aware capability gating. |
| v0.1.1 | April 14, 2026 | Polished aug1 create with interactive engine and model selection, a welcome banner, clearer engine/augment language, and selected-provider .env examples. |
| v0.1.0 | April 14, 2026 | First working runtime: kernel, CLI, six augments, three model engines, AG-UI SSE chat, YAML config, memory, URL fetch, org knowledge, and operator escalation. |

## How to read this

- Tagged versions are release history. They should map to installable npm behavior when the package was published.
- Feature Status remains the support boundary for the docs site. When a changelog entry and a feature page appear to disagree, follow the page status label and the Feature Status matrix.
- Examples should only be treated as current implementation patterns when their page status matches the release state you are targeting.

## Related

- [CLI reference](https://auggy.dev/docs/cli-reference/markdown)