Point TypeDoc at docs/api instead of docs, and restore what it deleted

The two deleted files were not an editorial decision. typedoc.json set
"out": "docs", and TypeDoc empties its output directory before generating,
so running it locally wiped docs/cookbook/ and the deletions were picked up
as part of the diff.

That is a live bug on main, and it just got worse: #157 removed docs/ from
.gitignore, so the next person to run npx typedoc would have deleted
DUAL_NETWORK.md, backup-restore.md, event-reference.md and the cookbook, and
git would have staged all of it.

- typedoc.json: out -> docs/api, so generated and hand-written docs no longer
  share a directory. Kept this PR's name, entryPointStrategy and
  navigationLinks additions.
- Restored docs/cookbook/portfolio.md and dashboard-preview.jpg from main.
- Restored the npm run docs:openapi step the workflow rewrite dropped. Without
  it the published site keeps a stale OpenAPI spec, and nothing else reads
  that file so nothing would have flagged it.
- .gitignore ignores docs/openapi.json and docs/api/ specifically, rather than
  docs/ wholesale — the generated artefacts, not the guides.

Kept from this PR: npm ci without the || npm install fallback (a lockfile
desync should fail rather than silently resolve differently),
peaceiris/actions-gh-pages@v4, and keep_files.

Verified by running npx typedoc: output lands in docs/api and every
hand-written doc is still there afterwards.

Author: Miracle656

.github/workflows/typedoc.yml

@@ -28,6 +28,15 @@ jobs:
       - name: Generate Prisma client
         run: npx prisma generate
 
+      # Regenerates docs/openapi.json, which is published alongside the
+      # TypeDoc output. Dropping it would leave the hosted site with a stale
+      # OpenAPI spec — silently, since nothing else reads that file.
+      - name: Generate OpenAPI document
+        run: npm run docs:openapi
+
+      # TypeDoc writes to docs/api (see typedoc.json). It empties its output
+      # directory first, so it must NOT point at docs/ itself — that is what
+      # deleted docs/cookbook in an earlier revision of this PR.
       - name: Build TypeDoc HTML
         run: npx typedoc
 

.gitignore

@@ -1,7 +1,9 @@
 node_modules/
 dist/
-# Generated by `npm run docs:openapi` alongside the tracked root openapi.json.
+# Generated docs output. docs/ itself is tracked (hand-written guides live
+# there); only the generated artefacts inside it are ignored.
 docs/openapi.json
+docs/api/
 .env
 *.env.local
 bench/results.json

docs/cookbook/dashboard-preview.jpg

@@ -0,0 +1,52 @@
+# Recipe: Portfolio Tracker
+
+This recipe demonstrates how to build a React dashboard connecting the Wraith API's `/summary` and `/transfers` endpoints to display an address's token holdings and recent activity.
+
+![Portfolio Dashboard Preview](./dashboard-preview.jpg)
+
+## Overview
+
+While Wraith natively indexes Soroban contract events, it exposes a robust REST API perfect for building user-facing dashboards. In this example, we connect two powerful endpoints:
+
+1. `GET /summary/:address` to calculate the current token balances (net flow) along with total tokens received and sent.
+2. `GET /transfers/address/:address` to get a chronological history of all incoming and outgoing token transfers.
+
+## Runnable Example
+
+We have provided a complete, deployable Vite + React application in the repository under `examples/portfolio-dashboard`.
+
+### Quick Start
+
+1. Ensure the Wraith backend is running locally on port 3000 (see [Quick Start](../../README.md#quick-start)).
+2. Navigate to the example directory and start the frontend:
+
+```bash
+cd examples/portfolio-dashboard
+npm install
+npm run dev
+```
+
+3. Open `http://localhost:5173` in your browser.
+
+## Code Walkthrough
+
+The core logic uses `Promise.all` to fetch data from both endpoints concurrently, minimizing the loading time for the user. 
+
+```typescript
+// From examples/portfolio-dashboard/src/App.tsx
+
+const [summaryRes, transfersRes] = await Promise.all([
+  fetch(`${API_URL}/summary/${targetAddress}`),
+  fetch(`${API_URL}/transfers/address/${targetAddress}?limit=10`)
+]);
+
+const summaryData = await summaryRes.json();
+const transfersData = await transfersRes.json();
+```
+
+### Data Structures
+
+- **Summary endpoint** returns an array of `tokens`, giving us the `displayNetFlow` (current balance) and `contractId`.
+- **Transfers endpoint** returns `transfers` containing individual ledger events, marked with a `direction` of `incoming` or `outgoing`.
+
+By simply formatting this data into a grid of holdings and a table of transfers, you get a fully functional portfolio tracker without needing complex indexer logic on the frontend.

docs/cookbook/portfolio.md

@@ -11,7 +11,7 @@
     "src/indexer.ts"
   ],
   "entryPointStrategy": "resolve",
-  "out": "docs",
+  "out": "docs/api",
   "theme": "default",
   "readme": "README.md",
   "includeVersion": true,