feat(cli): forge try — instant-gratification onboarding (#350)

.claude/skills/forge.md

@@ -887,6 +887,7 @@ Full reference: `docs/reference/cli-reference.md`.
 
 | Subcommand | Purpose | Key flags |
 |---|---|---|
+| `forge try` | Instant demo: scaffold a keyless demo agent (native executor + `weather` skill + safe builtins) into a temp dir and chat in-process with the tool/egress loop rendered inline. No server/build. Credential auto-resolved (flags → env key → OpenAI OAuth → Ollama → picker); nothing on disk unless `--keep`. Same runtime as `forge run`, no A2A server | `--provider`, `--model`, `--once <prompt>`, `--keep`, `--quiet`, `--audit` |
 | `forge init` | Scaffold a new agent: `forge.yaml`, `.env`, `SKILL.md`, `guardrails.json`. Interactive TUI by default; `--non-interactive` for CI | `--model-provider`, `--model-name`, `--channels`, `--auth`, `--from-skills`, `--compression` |
 | `forge build` | Run the build pipeline → `.forge-output/agent.json` + container Dockerfile + K8s manifests + (optional) signature | `--output-dir`, `--sign` |
 | `forge validate` | Lint `forge.yaml` + SKILL.md. `--platform-policy=PATH` lints a policy file standalone | `--strict`, `--command-compat`, `--platform-policy` |
@@ -899,7 +900,7 @@ Full reference: `docs/reference/cli-reference.md`.
 | `forge tool list \| describe` | Enumerate registered tools, show schemas | |
 | `forge channel add \| list \| status \| serve \| disable \| enable` | Channel adapters; disable/enable edit the user policy layer by default; `--system` retargets `/etc/forge/policy.yaml` | `--with`, `--system` |
 | `forge secret set \| get \| list \| delete` | Encrypted secrets | |
-| `forge auth show-token \| mint-token \| secret-yaml` | Operator UX for the internal bearer token at `<root>/.forge/runtime.token` (same token channel adapters + K8s CronJob trigger pods use). `secret-yaml` prints a ready-to-apply K8s Secret manifest sourced from the local token; `mint-token` is for first-deploy bootstrap. `forge.agent.id` label always tracks `forge.yaml` `agent_id`, never the `--name` override. (#162 part 1, PR #168) | `--namespace`, `--name` |
+| `forge auth show-token \| mint-token \| secret-yaml \| logout` | Operator UX for the internal bearer token at `<root>/.forge/runtime.token` (same token channel adapters + K8s CronJob trigger pods use). `secret-yaml` prints a ready-to-apply K8s Secret manifest sourced from the local token; `mint-token` is for first-deploy bootstrap. `logout [provider]` clears a stored LLM OAuth credential (default openai) so the next `forge init`/`forge try` re-prompts sign-in — laptop/dev only, **refuses inside an agent runtime** (container or `FORGE_PLATFORM_TOKEN` set). `forge.agent.id` label always tracks `forge.yaml` `agent_id`, never the `--name` override. (#162 part 1, PR #168) | `--namespace`, `--name` |
 | `forge key generate \| sign \| verify` | Ed25519 build artifact signing | |
 | `forge skills add \| list \| validate \| audit` | Registry: install, search, validate binary/env deps, security audit `--embedded` | `--category`, `--tags`, `--embedded` |
 | `forge mcp list \| test \| login \| logout` | Manage MCP servers + OAuth tokens | `--call <tool>`, `--args '<json>'` |
@@ -1033,6 +1034,11 @@ guardrails_path: guardrails.json
 
 ## 15. How to create an agent
 
+For a first taste, `forge try` scaffolds a keyless demo agent and drops you into
+a chat with the tool/egress loop rendered inline (ephemeral by default;
+`forge try --keep` writes it to `./forge-quickstart`). The pipeline below is for
+building your own from scratch.
+
 ```bash
 # 1. Scaffold
 forge init my-agent --model-provider anthropic --channels slack --non-interactive

README.md

@@ -23,19 +23,31 @@ Forge is the open-source runtime for Anthropic's Agent Skills standard — built
 
 ## Quick Start
 
+Talk to a working agent, and watch it use a tool, in under 60 seconds:
+
 ```bash
-# Install (pick one)
-brew install initializ/tap/forge
-curl -sSL https://raw.githubusercontent.com/initializ/forge/main/install.sh | bash
+brew install initializ/tap/forge && forge try
+```
+
+`forge try` scaffolds a keyless demo agent, finds whatever model credential you
+already have, and drops you into a chat whose every tool call and egress check
+renders inline:
 
-# Create and run an agent
-forge init my-agent && cd my-agent && forge run
+```
+you › what's the weather in Tokyo, should I pack an umbrella?
+
+  ▸ tool   weather_current(location=Tokyo)
+  ▸ egress wttr.in   ✓ allowed
+  ◂ 18C, light rain this evening
 
-# Connect to Slack
-forge run --with slack
+agent › 18C in Tokyo with light rain tonight. Yes, take the umbrella.
 ```
 
-See [Quick Start](docs/getting-started/quick-start.md) for the full walkthrough, or [Installation](docs/getting-started/installation.md) for all methods.
+Then build your own: `forge try --keep` graduates the demo to `./forge-quickstart`.
+
+See [Quick Start](docs/getting-started/quick-start.md) for the walkthrough,
+[Ship to Production](docs/getting-started/ship-to-production.md) for the full
+pipeline, or [Installation](docs/getting-started/installation.md) for all methods.
 
 ## How It Works
 
@@ -73,7 +85,8 @@ You write a `SKILL.md`. Forge compiles it into a secure, runnable agent with egr
 
 | Document | Description |
 |----------|-------------|
-| [Quick Start](docs/getting-started/quick-start.md) | Get an agent running in 60 seconds |
+| [Quick Start](docs/getting-started/quick-start.md) | Talk to an agent in 60 seconds with `forge try` |
+| [Ship to Production](docs/getting-started/ship-to-production.md) | The full init, build, package, deploy pipeline |
 | [Installation](docs/getting-started/installation.md) | Homebrew, binary, and Windows install |
 | [Architecture](docs/core-concepts/how-forge-works.md) | System design, module layout, and data flows |
 

docs/core-concepts/runtime-engine.md

@@ -211,6 +211,16 @@ Executor selection happens in `runner.go` based on framework type and configurat
 
 ## Running Modes
 
+### `forge try` — In-Process Demo
+
+`forge try` runs the demo agent **in-process** — no HTTP server, daemon, or port binding. It builds the same `LLMExecutor` `forge run` uses (built-in tool registry, egress-enforced client + subprocess proxy, audit + progress hooks, provider client) via a trimmed bootstrap (`forge-cli/runtime/local_session.go`) and drives it from a stdin REPL, one turn per line, with conversation history held in memory (the executor `Store` is nil, so nothing persists). It's the 60-second on-ramp; see the [Quick Start](../getting-started/quick-start.md) and the [`forge try` CLI reference](../reference/cli-reference.md#forge-try).
+
+```bash
+forge try                                   # interactive
+forge try --once "what's 17% of 4,200?"     # one-shot
+forge try --keep                            # graduate to ./forge-quickstart
+```
+
 ### `forge run` — Foreground Server
 
 Run the agent as a foreground HTTP server. Used for development and container deployments.

docs/getting-started/quick-start.md

@@ -1,51 +1,83 @@
 ---
 title: "Quick Start"
-description: "Get a Forge agent running in under 60 seconds."
+description: "Talk to a working agent in under 60 seconds with forge try."
 order: 2
 ---
 
-Get a Forge agent running in under 60 seconds.
+Talk to a working agent, and watch it use a tool, in under 60 seconds. One command:
 
-## Why Forge?
+```bash
+brew install initializ/tap/forge && forge try
+```
 
-**Instant Agent From a Single Command**
+No build, no cluster, no config. `forge try` scaffolds a keyless demo agent into
+a throwaway workspace, finds whatever model credential you already have (an env
+key, an OpenAI sign-in, or a local Ollama), and drops you into a chat whose every
+tool call and egress check renders inline.
 
-Write a SKILL.md. Run `forge init`. Your agent is live.
+## What it looks like
 
-The wizard configures your model provider, validates your API key,
-connects Slack or Telegram, picks skills, and starts your agent.
-Zero to running in under 60 seconds.
+```
+$ forge try
 
-**Secure by Default**
+  forge try: talking to a live agent in your terminal.
+  No build, no cluster. Ctrl-D or /exit to quit.
 
-Forge is designed for safe execution:
+  Using OpenAI (signed in).
+  Agent: quickstart · skills: weather · tools: http_request, datetime_now, math_calculate
 
-* Does NOT create public tunnels
-* Does NOT expose webhooks automatically
-* Uses outbound-only connections (Slack Socket Mode, Telegram polling)
-* Enforces outbound domain allowlists at both build-time and runtime, including subprocess HTTP via a local egress proxy
-* Encrypts secrets at rest (AES-256-GCM) with per-agent isolation
-* Signs build artifacts (Ed25519) for supply chain integrity
-* Supports restricted network profiles with audit logging
+  Try:  what's the weather in Tokyo?
+        what's 17% of 4,200?
+        what time is it in UTC?
 
-No accidental exposure. No hidden listeners.
+you › what's the weather in Tokyo, should I pack an umbrella?
 
-## Get Started in 60 Seconds
+  ▸ tool   weather_current(location=Tokyo)
+  ▸ egress wttr.in   ✓ allowed
+  ◂ 18C, light rain this evening
 
-```bash
-# Install
-curl -sSL https://raw.githubusercontent.com/initializ/forge/main/install.sh | bash
+agent › 18C in Tokyo with light rain expected tonight. Yes, take the umbrella.
 
-# Initialize a new agent (interactive wizard)
-forge init my-agent
+  audit  {"tools":["weather_current"],"egress":["wttr.in:allow"]}
 
-# Run locally
-cd my-agent && forge run
+you › ^D
 
-# Run with Telegram
-forge run --with telegram
+  You just ran an agent whose every tool call and egress you can see and audit.
+  Want to keep it and make it yours?  ->  forge try --keep   (writes ./forge-quickstart)
+  Then edit skills/, run it as a service with forge serve, or deploy with forge package.
 ```
 
-The `forge init` wizard walks you through model provider, API key, fallback providers, tools, skills, and channel setup. Use `--non-interactive` with flags for scripted setups.
+The inline `▸ tool` / `▸ egress` lines are the agent's own audit stream, the same
+signal the enterprise story rests on, surfaced as the first-run view. Add `--audit`
+to see the full NDJSON, or `--quiet` to hide the loop.
+
+## One-shot mode
+
+For a non-interactive taste (CI, docs, a quick check):
+
+```bash
+forge try --once "what's 2 + 2?"
+```
+
+## No credential yet?
+
+`forge try` resolves, in order: an explicit `--provider`/`--model`, then an env
+key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY`), then a saved
+OpenAI sign-in, then a local [Ollama](https://ollama.com) daemon. With none of
+those, it offers a one-time picker (sign in with OpenAI, paste a key, or use
+Ollama). Nothing is written to disk unless you pass `--keep`.
+
+## The ladder
+
+`forge try` is rung one. Each step adds one capability:
+
+1. **60s** — `forge try`: talk to an agent, watch it use a tool.
+2. **5 min** — `forge try --keep`, then edit `skills/<name>/SKILL.md` and add a skill. See [Your First Skill](your-first-skill.md).
+3. **15 min** — `forge serve`, tail the audit log, add a guardrail and watch it block. See [Ship to Production](ship-to-production.md).
+4. **Ship** — `forge package`: an egress-enforced container into your own cluster. See [Ship to Production](ship-to-production.md).
+
+## Next steps
 
-See [Installation](installation.md) for all installation methods.
+- [Your First Skill](your-first-skill.md) — teach the agent something new.
+- [Ship to Production](ship-to-production.md) — the full init -> build -> package -> deploy pipeline.
+- [Installation](installation.md) — every install method.

docs/getting-started/ship-to-production.md

@@ -0,0 +1,95 @@
+---
+title: "Ship to Production"
+description: "The full pipeline: init, skills, secrets, validate, build, package, deploy."
+order: 3
+---
+
+Once [`forge try`](quick-start.md) has shown you a working agent, this is the
+path to a deployable one you own: scaffold it, give it skills and secrets,
+validate, build, and package it into an egress-enforced container for your own
+cluster. Each step is independently runnable.
+
+## 1. Scaffold
+
+```bash
+forge init my-agent
+cd my-agent
+```
+
+The interactive wizard configures the model provider, validates the API key,
+optionally connects a channel (Slack / Telegram), picks skills, and sets the
+egress allowlist. For scripted setups, use flags with `--non-interactive`:
+
+```bash
+forge init my-agent --model-provider anthropic --non-interactive
+```
+
+`forge try --keep` writes the same layout to `./forge-quickstart`, so you can
+graduate the demo agent instead of starting from scratch.
+
+## 2. Add skills
+
+Skills are the agent's capabilities. Install from the registry or write your own:
+
+```bash
+forge skills add tavily-research        # registry skill
+# or author skills/<name>/SKILL.md by hand
+```
+
+See [Your First Skill](your-first-skill.md) for the SKILL.md format.
+
+## 3. Configure secrets
+
+Secrets are encrypted at rest (AES-256-GCM), per-agent:
+
+```bash
+forge secret set ANTHROPIC_API_KEY sk-...
+forge secret set SLACK_BOT_TOKEN xoxb-...
+```
+
+## 4. Validate
+
+Catch config, egress, and policy problems before building:
+
+```bash
+forge validate
+```
+
+## 5. Run locally
+
+```bash
+forge run                 # A2A server on :8080
+forge serve               # long-running service
+forge run --with slack    # attach a channel
+```
+
+Tail the audit log while it runs to see tool calls, egress decisions, and
+guardrail blocks, the same stream `forge try` renders inline.
+
+## 6. Build
+
+Compile the agent and its dependencies into a runnable artifact. Build-time
+egress allowlisting and Ed25519 artifact signing happen here:
+
+```bash
+forge build
+```
+
+## 7. Package and deploy
+
+Produce an egress-enforced container image and the deployment manifests for your
+cluster:
+
+```bash
+forge package
+```
+
+The generated image enforces the outbound domain allowlist at runtime (including
+subprocess HTTP via the local egress proxy), so the deployed agent has the same
+network posture you validated locally. Deploy it with your own pipeline.
+
+## Related
+
+- [Quick Start](quick-start.md) — the 60-second `forge try` on-ramp.
+- [Your First Skill](your-first-skill.md) — author a SKILL.md.
+- [Installation](installation.md) — every install method.

docs/reference/cli-reference.md

@@ -126,6 +126,36 @@ See [Authentication](../security/authentication.md) for the full auth provider r
 
 ---
 
+## `forge try`
+
+Talk to a working demo agent in your terminal in under 60 seconds — no build, no cluster, no config. Scaffolds a keyless demo agent (the native forge LLM executor + the `weather` skill + `http_request`/`datetime_now`/`math_calculate` builtins) into a throwaway workspace, resolves whatever model credential is available, and drops you into a chat whose tool calls and egress checks render inline. See the [Quick Start](../getting-started/quick-start.md) for the full walkthrough.
+
+```bash
+# Interactive: resolves a credential, then chat
+forge try
+
+# One-shot (CI / docs / a quick check)
+forge try --once "what's 17% of 4,200?"
+
+# Keep the demo agent to make it your own (writes ./forge-quickstart)
+forge try --keep
+```
+
+| Flag | Description |
+|------|-------------|
+| `--provider` | Model provider: `openai`, `anthropic`, `gemini`, or `ollama`. Skips auto-resolution. |
+| `--model` | Model name (defaults to the provider's default). |
+| `--once <prompt>` | Run a single prompt non-interactively, then exit. |
+| `--keep` | Write the demo agent to `./forge-quickstart` instead of an auto-cleaned temp dir. |
+| `--quiet` | Hide the inline tool/egress loop lines. |
+| `--audit` | Show the full NDJSON audit event stream instead of the compact summary. |
+
+**Credential resolution order:** explicit `--provider`/`--model` → env key (`ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `GEMINI_API_KEY`) → saved OpenAI OAuth session → local [Ollama](https://ollama.com) daemon → interactive picker (sign in with OpenAI, paste a key, or use Ollama). Nothing is written to disk unless you pass `--keep`; a pasted key is held in memory only. Use [`forge auth logout`](#forge-auth) to clear a saved OAuth session and re-show the picker.
+
+The demo runs the same runtime as `forge run` (tool registry, egress enforcement, audit + progress hooks) in-process — no A2A server, daemon, or port binding. Exit with `/exit`, Ctrl-D, or Ctrl-C.
+
+---
+
 ## `forge compression`
 
 Inspect context compression state.
@@ -532,10 +562,17 @@ forge auth secret-yaml --name custom-secret-name
 # Common one-liner: populate the Secret a `forge package` deploy
 # expects from the local runtime.token.
 forge auth secret-yaml | kubectl apply -f -
+
+# Remove a stored LLM OAuth credential (default: openai) so the next
+# `forge init` / `forge try` prompts you to sign in again.
+forge auth logout
+forge auth logout openai
 ```
 
 The `forge.agent.id` label on the generated Secret is always sourced from `forge.yaml`'s `agent_id` (or the `"forge-agent"` fallback), never from the `--name` override — so operators using `--name` to match an existing cluster convention still see telemetry and label-selectors keyed on the real agent ID.
 
+`forge auth logout` is an operator/laptop command: it deletes the OAuth credential from `~/.forge/credentials` and the encrypted store, and **refuses to run inside an agent runtime** — a container, or when `FORGE_PLATFORM_TOKEN` is set. A deployed agent authenticates with an injected API key or platform token, not the OAuth credential store, so there is nothing there for the runtime to log out of; the refusal is defense-in-depth so Forge is never the tool an agent shells out to in order to wipe an operator's credential.
+
 ---
 
 ## `forge key`

forge-cli/cmd/auth.go

@@ -214,4 +214,5 @@ func init() {
 	authCmd.AddCommand(authShowTokenCmd)
 	authCmd.AddCommand(authMintTokenCmd)
 	authCmd.AddCommand(authSecretYAMLCmd)
+	authCmd.AddCommand(authLogoutCmd)
 }