HyperTekOrg · adiman9 · Feb 25, 2026 · Feb 22, 2026 · Feb 22, 2026 · Feb 25, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -136,15 +136,13 @@ jobs:
 
       - name: Build stack crates (regenerate ASTs)
         run: |
-          cargo build --manifest-path stacks/pumpfun/Cargo.toml
           cargo build --manifest-path stacks/ore/Cargo.toml
 
       - name: Install hyperstack-cli
         run: cargo install --path cli
 
       - name: Regenerate TypeScript SDKs
         run: |
-          hs sdk create typescript pumpfun --config stacks/pumpfun/hyperstack.toml
           hs sdk create typescript ore --config stacks/ore/hyperstack.toml
 
       - name: Check for uncommitted changes
@@ -160,9 +158,7 @@ jobs:
             echo ""
             echo "To fix this, run the following locally and commit the changes:"
             echo ""
-            echo "  cargo build --manifest-path stacks/pumpfun/Cargo.toml"
             echo "  cargo build --manifest-path stacks/ore/Cargo.toml"
-            echo "  hs sdk create typescript pumpfun --config stacks/pumpfun/hyperstack.toml"
             echo "  hs sdk create typescript ore --config stacks/ore/hyperstack.toml"
             echo ""
             echo "Files that differ:"

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -20,10 +20,13 @@ export default defineConfig({
           description:
             "Hyperstack is a system for programmable real-time data feeds on Solana. Stream any on-chain data to your app via WebSocket. Define data shapes in a Rust DSL, deploy, and consume with typed TypeScript, React, or Rust SDKs.",
           promote: [
+            "getting-started/what-is-hyperstack",
+            "agent-skills/setup-tools",
             "using-stacks/quickstart",
             "using-stacks/connect",
             "agent-skills/overview",
             "agent-skills/prompts",
+            "agent-skills/tutorial-ore-dashboard",
             "sdks/typescript",
             "sdks/react",
           ],
@@ -50,7 +53,11 @@ export default defineConfig({
       // Contributors only need to add frontmatter to control ordering
       sidebar: [
         {
-          label: "Get Started",
+          label: "Getting Started",
+          items: [{ slug: "getting-started/what-is-hyperstack" }],
+        },
+        {
+          label: "For Developers",
           autogenerate: { directory: "using-stacks" },
         },
         {

diff --git a/docs/public/agent.md b/docs/public/agent.md
@@ -2,8 +2,54 @@
 
 You are setting up Hyperstack, a real-time Solana data streaming platform. Follow these steps in order.
 
+## Step 0: Check What Is Already Installed
+
+Before installing anything, check what is already present.
+
+### Hyperstack CLI
+
+Run:
+```
+hs --version
+```
+
+- If this prints a version number, the CLI is already installed. Continue to check if it needs updating.
+- If the command is not found, the CLI needs to be installed (see Step 1).
+
+If the CLI is already installed, check if it is up to date:
+```
+cargo install hyperstack-cli 2>&1 | head -5
+```
+If this says "already up to date" or similar, skip Step 1. If a newer version is available, it will update in place.
+
+### Agent Skills
+
+Check if Hyperstack skills are already installed using the skills CLI:
+```
+npx skills list 2>/dev/null | grep -i hyperstack
+```
+
+- If this shows hyperstack skills, they are already installed. Run `npx skills check` to see if updates are available.
+- If no output, skills need to be installed (see Step 2).
+
+Alternatively, check for skill files directly in the project. The location depends on which agent you are:
+
+| Agent | Skill directory |
+|---|---|
+| Cursor | `.cursor/skills/` or `.agents/skills/` |
+| Claude Code | `.claude/skills/` |
+| OpenCode | `.opencode/skills/` or `.agents/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| Cline | `.cline/skills/` |
+| GitHub Copilot | `.agents/skills/` |
+| Other / Unknown | `.agents/skills/` |
+
+If skill files already exist and are up to date, skip Step 2.
+
 ## Step 1: Install the Hyperstack CLI
 
+Only do this if `hs --version` failed in Step 0.
+
 Preferred (Cargo):
 ```
 cargo install hyperstack-cli
@@ -21,20 +67,59 @@ hs --version
 
 ## Step 2: Install Agent Skills
 
+Only do this if skill files were not found in Step 0, or if you want to update to the latest version.
+
 The `npx skills` tool installs skills for 40+ coding agents including Cursor, Claude Code, OpenCode, Codex, Windsurf, VS Code Copilot, Cline, Roo Code, and many more. It auto-detects which agents are present and installs to the correct location for each.
 
+### Determine your agent identity
+
+Before running the install, determine which agent harness you are running in. This lets you target the install correctly and avoids unnecessary prompts.
+
+**How to tell which agent you are:**
+- If you have a system prompt or context that identifies you (e.g. "You are Claude Code", "Cursor Agent", etc.), use that identity.
+- If you can check your own configuration directory, look for which of these exist: `.claude/`, `.cursor/`, `.opencode/`, `.windsurf/`, `.cline/`.
+- If you genuinely cannot determine your identity, fall back to the general `.agents/` install.
+
+**If you know which agent you are**, install with the `--agent` flag for your specific harness. This ensures skills land in the correct directory:
+
+```
+npx skills add usehyperstack/skills --agent <your-agent>
+```
+
+Common agent identifiers:
+
+| Agent | Flag |
+|---|---|
+| Claude Code | `--agent claude-code` |
+| Cursor | `--agent cursor` |
+| OpenCode | `--agent opencode` |
+| Windsurf | `--agent windsurf` |
+| GitHub Copilot | `--agent github-copilot` |
+| Cline | `--agent cline` |
+| Codex | `--agent codex` |
+| Roo Code | `--agent roo` |
+| Gemini CLI | `--agent gemini-cli` |
+| Goose | `--agent goose` |
+| Continue | `--agent continue` |
+
+**If you cannot determine which agent you are**, fall back to the general install which writes to `.agents/skills/` (readable by most agents):
+
 ```
 npx skills add usehyperstack/skills
 ```
 
+This auto-detects which agents are present and installs to the correct location for each. You can also explicitly install for all detected agents:
+
+```
+npx skills add usehyperstack/skills --all
+```
+
 This installs context files that teach you (the agent) how to use Hyperstack's SDKs, CLI, and Rust DSL.
 
-If you need to target a specific agent, or want to understand the options available, see the full `npx skills` documentation: https://github.com/vercel-labs/skills
+For the full `npx skills` documentation: https://github.com/vercel-labs/skills
 
-Common options:
-- `npx skills add usehyperstack/skills --all` installs all skills to all detected agents without prompts
-- `npx skills add usehyperstack/skills -a claude-code` targets a specific agent
-- `npx skills add usehyperstack/skills -a cursor -a opencode` targets multiple agents
+Additional options:
+- `npx skills add usehyperstack/skills -a cursor -a opencode` targets multiple specific agents
 - `npx skills add usehyperstack/skills -g` installs globally (available across all projects)
 
 ## Step 3: Discover Available Data
@@ -69,4 +154,4 @@ Key rules:
 
 Full documentation: https://docs.usehyperstack.com
 Agent skills reference: https://docs.usehyperstack.com/agent-skills/overview/
-Prompt cookbook: https://docs.usehyperstack.com/agent-skills/prompts/
+Prompt cookbook: https://docs.usehyperstack.com/agent-skills/prompts/
diff --git a/docs/src/content/docs/agent-skills/explore.mdx b/docs/src/content/docs/agent-skills/explore.mdx
@@ -1,5 +1,5 @@
 ---
-title: Schema Discovery
+title: Explore Stacks
 sidebar:
   order: 3
 description: How agents use hs explore to discover stacks and get live schema information.

diff --git a/docs/src/content/docs/agent-skills/overview.mdx b/docs/src/content/docs/agent-skills/overview.mdx
@@ -1,101 +1,129 @@
 ---
-title: Build with AI
+title: Agent Skills
 sidebar:
   order: 1
-description: Let your AI agent set up and build with Hyperstack. One prompt, fully automated.
+description: How the Hyperstack CLI, agent skills, and agent.md work together to give your AI agent everything it needs to build with Hyperstack.
 ---
 
 import { Tabs, TabItem } from "@astrojs/starlight/components";
 import CopyPrompt from "../../../components/CopyPrompt.astro";
 
-The fastest way to start with Hyperstack is to let your AI agent handle everything. Paste one prompt and your agent installs the CLI, sets up skills, discovers available data, and starts building.
+:::tip[New to coding?]
+If you haven't set up an AI coding tool yet, start with [AI Tooling Setup](/agent-skills/setup-tools/) which walks you through everything from scratch.
+:::
+
+Hyperstack is designed to be built with AI agents. This page explains the three pieces that make that work: the **CLI**, the **agent skills**, and **agent.md**.
 
 ---
 
-## Let Your Agent Do It
+## The CLI
 
-Paste this into your AI coding agent (Cursor, Claude Code, OpenCode, Windsurf, or any agent that can read URLs):
+The Hyperstack CLI (`hs`) is the primary interface between your agent and Hyperstack. It handles scaffolding, deployment, SDK generation, and — most importantly — live schema discovery.
 
-<CopyPrompt>
-Read https://docs.usehyperstack.com/agent.md and follow the instructions to set up Hyperstack in this project
-</CopyPrompt>
+```bash
+# Install via Cargo (recommended)
+cargo install hyperstack-cli
 
-That's it. Your agent will:
+# Or via npm
+npm install -g hyperstack-cli
+```
 
-1. Install the Hyperstack CLI (prefers Cargo, falls back to npm)
-2. Install agent skills so it knows the SDK patterns
-3. Run `hs explore --json` to discover available data streams
-4. Be ready to build
+The key command for agents is `hs explore`:
 
-Once setup is complete, try asking:
+```bash
+hs explore --json
+```
 
-- "Build a React dashboard that displays live ORE mining rounds"
-- "Show me the current ORE motherlode and total miners in real-time"
-- "Create a custom stack from this IDL that tracks token balances"
-- "What entities does the ore stack have? Show me all fields."
+This queries the Hyperstack API and returns the live schemas for all available stacks — their entities, fields, views, and types. Because your agent runs this at setup time, it always works with accurate, up-to-date type information rather than guessing from training data.
 
 ---
 
-## How It Works
+## Agent Skills
 
-The setup prompt points your agent to a plain text instruction file. The agent reads it, executes the setup commands, and learns how to use Hyperstack through the installed skills.
+Agent skills are markdown files that teach your agent how to use Hyperstack correctly. They're installed into your project so your agent picks them up automatically as context.
 
-Agent skills are markdown files that teach your agent the SDK syntax, CLI commands, and patterns. The skills also instruct the agent to use the `hs` CLI for live data, so type information is always accurate.
+Three skills are installed:
 
-```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│  Agent Skills   │ ──▶ │   AI Agent      │ ──▶ │   Your Code     │
-│  (SDK patterns  │     │   (Cursor,      │     │   (correct      │
-│   + CLI usage)  │     │    Claude, etc.) │     │    from start)  │
-└─────────────────┘     └─────────┬───────┘     └─────────────────┘
-                                  │
-                         hs explore --json
-                                  │
-                        ┌─────────▼───────┐
-                        │  Hyperstack API  │
-                        │  (live schemas)  │
-                        └─────────────────┘
+| Skill                | What it teaches                                                           |
+| -------------------- | ------------------------------------------------------------------------- |
+| `hyperstack`         | Router skill — detects intent and routes the agent to the right sub-skill |
+| `hyperstack-consume` | SDK patterns for connecting to streams in TypeScript, React, and Rust     |
+| `hyperstack-build`   | Rust DSL syntax for building custom stacks from Solana program IDLs       |
+
+Install them manually with:
+
+```bash
+npx skills add usehyperstack/skills
 ```
 
-Three skills are installed:
+Once installed, your agent knows the correct hook names, view patterns, subscription syntax, and CLI commands. Without the skills, an agent will hallucinate API shapes based on outdated training data.
+
+---
+
+## agent.md
+
+`agent.md` is a plain text file hosted at `https://docs.usehyperstack.com/agent.md`. It's the bootstrap instruction set — a single URL your agent can read to set everything up from scratch.
+
+When your agent reads `agent.md`, it:
+
+1. Installs the Hyperstack CLI (prefers Cargo, falls back to npm)
+2. Installs the agent skills into the project
+3. Runs `hs explore --json` to load live schemas
+4. Understands it's ready to build
 
-| Skill                | What It Teaches                                                                   |
-| -------------------- | --------------------------------------------------------------------------------- |
-| `hyperstack`         | Router skill that detects your intent and points the agent to the right sub-skill |
-| `hyperstack-consume` | SDK patterns for connecting to streams and building UIs (TypeScript, React, Rust) |
-| `hyperstack-build`   | Rust DSL syntax for building custom stacks from Solana program IDLs               |
+This is why the one-liner works:
+
+<CopyPrompt>
+Read https://docs.usehyperstack.com/agent.md and follow the instructions to set up Hyperstack in this project
+</CopyPrompt>
 
 ---
 
-## Prefer to Set Up Manually?
+## How They Fit Together
+
+```
+agent.md  ──▶  CLI installed  ──▶  hs explore --json  ──▶  live schemas
+               Skills installed ─▶  SDK patterns + DSL syntax
+
+                         ┌────────────────────────────┐
+                         │         AI Agent            │
+                         │  (Cursor, Claude Code, etc) │
+                         │                             │
+                         │  Skills  +  Live schemas    │
+                         └────────────┬───────────────┘
+                                      │
+                              builds correct code
+                                      │
+                                      ▼
+                               Your Hyperstack app
+```
 
-If you'd rather run the commands yourself instead of letting the agent handle it:
+The CLI gives the agent **live data**. The skills give the agent **correct patterns**. Together they remove the two main failure modes: wrong types and wrong API usage.
+
+---
+
+## Prefer to Set Up Manually?
 
 <Tabs>
 <TabItem label="New Project">
 
 ```bash
-# Install the CLI
 cargo install hyperstack-cli
 # Or: npm install -g hyperstack-cli
 
-# Scaffold an app
-npx hyperstack-cli create my-app
+npx hyperstack-cli create my-app --template react-ore
 cd my-app
 
-# Install agent skills
 npx skills add usehyperstack/skills
 ```
 
 </TabItem>
 <TabItem label="Existing Project">
 
 ```bash
-# Install the CLI
 cargo install hyperstack-cli
 # Or: npm install -g hyperstack-cli
 
-# Install agent skills in your project
 npx skills add usehyperstack/skills
 ```
 
@@ -108,7 +136,7 @@ For editor-specific file locations and manual configuration, see [Editor Setup](
 
 ## Next Steps
 
-- [Prompt Cookbook](/agent-skills/prompts/) - Copy-paste prompts for common tasks
-- [Tutorial: ORE Dashboard](/agent-skills/tutorial-ore-dashboard/) - Build a complete app with step-by-step prompts
-- [Schema Discovery](/agent-skills/explore/) - How `hs explore` provides live type information
-- [Editor Setup](/agent-skills/setup/) - Manual setup for specific editors
+- [Prompt Cookbook](/agent-skills/prompts/) — Copy-paste prompts for common tasks
+- [Tutorial: ORE Dashboard](/agent-skills/tutorial-ore-dashboard/) — Build a complete app step by step
+- [Schema Discovery](/agent-skills/explore/) — How `hs explore` provides live type information
+- [Editor Setup](/agent-skills/setup/) — Manual setup for specific editors