cacheplane
diff --git a/‎apps/website/content/docs-v2/concepts/agent-architecture.mdx‎
Lines changed: 55 additions & 0 deletions b/‎apps/website/content/docs-v2/concepts/agent-architecture.mdx‎
Lines changed: 55 additions & 0 deletions
diff --git a/‎apps/website/content/docs-v2/concepts/angular-signals.mdx‎
Lines changed: 61 additions & 0 deletions b/‎apps/website/content/docs-v2/concepts/angular-signals.mdx‎
Lines changed: 61 additions & 0 deletions
diff --git a/‎apps/website/content/docs-v2/concepts/langgraph-basics.mdx‎
Lines changed: 51 additions & 0 deletions b/‎apps/website/content/docs-v2/concepts/langgraph-basics.mdx‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎apps/website/content/docs-v2/concepts/state-management.mdx‎
Lines changed: 69 additions & 0 deletions b/‎apps/website/content/docs-v2/concepts/state-management.mdx‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎apps/website/content/docs-v2/getting-started/installation.mdx‎
Lines changed: 102 additions & 0 deletions b/‎apps/website/content/docs-v2/getting-started/installation.mdx‎
Lines changed: 102 additions & 0 deletions
@@ -0,0 +1,55 @@
+# Agent Architecture
+
+How AI agents work — the planning, execution, and tool-calling lifecycle that streamResource() connects your Angular app to.
+
+## The agent loop
+
+An AI agent follows a cycle:
+
+<Steps>
+<Step title="Receive input">
+The user sends a message via `submit()`. streamResource() posts it to LangGraph Platform.
+</Step>
+<Step title="Plan">
+The LLM decides what to do next — respond directly, call a tool, or delegate to a subagent.
+</Step>
+<Step title="Execute">
+Tools run (database queries, API calls, code execution). Results feed back into state.
+</Step>
+<Step title="Respond">
+The agent streams its response token-by-token. streamResource() updates the `messages()` signal in real-time.
+</Step>
+<Step title="Checkpoint">
+State is checkpointed. The agent may loop back to Plan, or finish.
+</Step>
+</Steps>
+
+## Tool calling
+
+Agents extend their capabilities through tools. streamResource() tracks tool execution:
+
+```typescript
+const agent = streamResource<AgentState>({
+  assistantId: 'research_agent',
+});
+
+// Currently executing tools
+const tools = computed(() => agent.toolProgress());
+
+// Completed tool calls with results
+const completedTools = computed(() => agent.toolCalls());
+```
+
+## Multi-agent patterns
+
+Complex tasks use multiple agents working together:
+
+- **Orchestrator** — one agent delegates to specialized subagents
+- **Pipeline** — agents process sequentially, each refining the output
+- **Debate** — agents review each other's work
+
+streamResource() supports these patterns through the `subagents()` and `activeSubagents()` signals.
+
+<Callout type="tip" title="Start simple">
+Most applications only need a single agent with tools. Add subagents when you need true task delegation with isolated state.
+</Callout>
@@ -0,0 +1,61 @@
+# Angular Signals
+
+streamResource() is built on Angular Signals — the reactive primitive introduced in Angular 16+. Every property on a StreamResourceRef is a Signal, making it work seamlessly with OnPush change detection, computed values, and effect callbacks.
+
+## Signals primer
+
+A Signal is a reactive value container. When a Signal's value changes, Angular automatically re-renders any template that reads it.
+
+```typescript
+// streamResource returns Signals, not Observables
+const chat = streamResource<ChatState>({ assistantId: 'agent' });
+
+chat.messages()    // Signal<BaseMessage[]> — call to read
+chat.status()      // Signal<ResourceStatus>
+chat.error()       // Signal<unknown>
+chat.isLoading()   // Signal<boolean> (computed)
+```
+
+## Computed values
+
+Use `computed()` to derive new Signals from streamResource signals.
+
+```typescript
+const lastMessage = computed(() =>
+  chat.messages().at(-1)?.content ?? ''
+);
+
+const messageCount = computed(() =>
+  chat.messages().length
+);
+
+const isIdle = computed(() =>
+  chat.status() === 'idle'
+);
+```
+
+## OnPush change detection
+
+Because Signals trigger change detection automatically, streamResource works perfectly with `ChangeDetectionStrategy.OnPush`.
+
+```typescript
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    @for (msg of chat.messages(); track $index) {
+      <p>{{ msg.content }}</p>
+    }
+  `,
+})
+export class ChatComponent {
+  chat = streamResource<ChatState>({ assistantId: 'agent' });
+}
+```
+
+## No RxJS required
+
+Unlike traditional Angular HTTP patterns, streamResource doesn't use Observables. There are no subscriptions to manage, no async pipes needed, and no memory leak risks.
+
+<Callout type="tip" title="Why Signals over RxJS?">
+Signals are simpler for UI state. They synchronously read the latest value, compose with computed(), and integrate with Angular's template syntax. streamResource handles the async SSE connection internally and surfaces results as Signals.
+</Callout>
@@ -0,0 +1,51 @@
+# LangGraph Basics
+
+LangGraph is a framework for building stateful AI agents as directed graphs. This page explains the core concepts for Angular developers who are new to agent development.
+
+## Graphs, nodes, and edges
+
+A LangGraph agent is a directed graph where:
+
+<Steps>
+<Step title="Nodes are functions">
+Each node performs one action — calling an LLM, querying a database, or making an API request. Nodes receive state and return updated state.
+</Step>
+<Step title="Edges define flow">
+Edges connect nodes. Conditional edges route execution based on state, enabling branching logic.
+</Step>
+<Step title="State is shared">
+All nodes read from and write to a shared state object. This state is what streamResource() exposes through its signals.
+</Step>
+</Steps>
+
+## How streamResource connects
+
+Your Angular app doesn't run the graph — LangGraph Platform does. streamResource() is the bridge:
+
+1. Your component calls `submit()` with user input
+2. FetchStreamTransport sends an HTTP POST to LangGraph Platform
+3. The platform runs the graph and streams state updates via SSE
+4. streamResource() updates its Signals as events arrive
+5. Angular re-renders your templates automatically
+
+## State design
+
+The generic type parameter in `streamResource<T>()` defines your agent's state shape.
+
+```typescript
+// Simple chat state
+streamResource<{ messages: BaseMessage[] }>({ ... })
+
+// Rich agent state with custom fields
+interface AgentState {
+  messages: BaseMessage[];
+  plan: string[];
+  currentStep: number;
+  results: Record<string, unknown>;
+}
+streamResource<AgentState>({ ... })
+```
+
+<Callout type="info" title="Learn more">
+For deeper LangGraph concepts (persistence, interrupts, memory), see the individual guide pages.
+</Callout>
@@ -0,0 +1,69 @@
+# State Management
+
+How state flows through streamResource() — from LangGraph's server-side state machine to Angular Signals in your templates.
+
+## State lives on the server
+
+Unlike traditional Angular state management (NgRx, signals stores), agent state lives on the LangGraph Platform. Your Angular app is a stateless view layer.
+
+```
+LangGraph Platform (source of truth)
+  ↓ SSE stream
+FetchStreamTransport (transport layer)
+  ↓ events
+streamResource() (signal conversion)
+  ↓ Signals
+Angular templates (reactive rendering)
+```
+
+## The state shape
+
+Your state type defines what the agent manages. The `value()` signal exposes the full state object.
+
+```typescript
+interface ProjectState {
+  messages: BaseMessage[];
+  files: string[];
+  analysis: { score: number; issues: string[] };
+}
+
+const agent = streamResource<ProjectState>({
+  assistantId: 'project_agent',
+});
+
+// Access any state field as a reactive value
+const files = computed(() => agent.value().files);
+const score = computed(() => agent.value().analysis.score);
+```
+
+## Thread state vs application state
+
+<Callout type="info" title="Two kinds of state">
+Thread state (managed by LangGraph) and application state (managed by Angular) are separate concerns. Don't try to sync them — read thread state from signals, manage UI state with Angular signals.
+</Callout>
+
+```typescript
+// Thread state — from the agent
+const messages = agent.messages();     // Read-only signal
+const agentStatus = agent.status();    // Read-only signal
+
+// Application state — your Angular code
+const sidebarOpen = signal(true);      // Your UI state
+const selectedTab = signal('chat');    // Your UI state
+```
+
+## State updates are immutable
+
+Every state update from the agent creates a new signal value. Angular's change detection picks this up automatically.
+
+```typescript
+// This works with OnPush because the Signal reference changes
+@for (msg of agent.messages(); track $index) {
+  <p>{{ msg.content }}</p>
+}
+
+// Computed values re-evaluate when dependencies change
+const hasErrors = computed(() =>
+  agent.value().analysis.issues.length > 0
+);
+```
@@ -0,0 +1,102 @@
+# Installation
+
+Detailed setup guide for streamResource() in your Angular application.
+
+## Requirements
+
+<Steps>
+<Step title="Angular 20+">
+streamResource() uses Angular Signals and the modern injection context API. Angular 20 or later is required.
+</Step>
+<Step title="Node.js 18+">
+Required for the build toolchain and package installation.
+</Step>
+<Step title="LangGraph Platform">
+A running LangGraph agent accessible via HTTP. Can be local (langgraph dev) or deployed (LangGraph Cloud).
+</Step>
+</Steps>
+
+## Install the package
+
+```bash
+npm install @cacheplane/stream-resource
+```
+
+This installs the library and its peer dependencies including `@langchain/langgraph-sdk`.
+
+## Configure the provider
+
+Add `provideStreamResource()` to your application configuration. This sets global defaults for all streamResource instances.
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideStreamResource } from '@cacheplane/stream-resource';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideStreamResource({
+      apiUrl: process.env['LANGGRAPH_URL'] ?? 'http://localhost:2024',
+    }),
+  ],
+};
+```
+
+<Callout type="tip" title="Per-call overrides">
+Any option passed to `streamResource()` directly overrides the global provider config. You can set a default `apiUrl` globally and override it for specific agents.
+</Callout>
+
+## Environment setup
+
+<Tabs items={['Development', 'Production']}>
+<Tab>
+
+For local development, run a LangGraph server:
+
+```bash
+# Start LangGraph dev server
+langgraph dev
+
+# Your agent will be available at http://localhost:2024
+```
+
+</Tab>
+<Tab>
+
+For production, point to your LangGraph Cloud deployment:
+
+```typescript
+provideStreamResource({
+  apiUrl: 'https://your-project.langgraph.app',
+})
+```
+
+</Tab>
+</Tabs>
+
+## Verify installation
+
+Create a minimal test to verify the setup works:
+
+```typescript
+import { streamResource } from '@cacheplane/stream-resource';
+
+// In a component
+const test = streamResource({
+  assistantId: 'chat_agent',
+});
+
+// If status() returns 'idle', the setup is correct
+console.log(test.status()); // 'idle'
+```
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" href="/docs/getting-started/quickstart">
+    Build your first chat component in 5 minutes
+  </Card>
+  <Card title="Angular Signals" href="/docs/concepts/angular-signals">
+    Understand how Signals power streamResource
+  </Card>
+</CardGroup>