docs: builder docs information architecture redesign

## Builder Docs Information Architecture

### Design Principle

Every page answers ONE question type. The type determines the section.

| Developer asks | Section |
|----------------|---------|
| "Set me up" | **Get Started** |
| "How do I build contracts?" | **Smart Contracts** (concepts + API) |
| "What tools are available?" | **Tools** (reference + guides, grouped by workflow) |
| "Walk me through building X" | **Tutorials** (multi-part guided learning) |
| "How do I upgrade?" | **Migration** |

Sections **link** to each other, never duplicate content.

---

## Final Structure

```
docs/builder/
│
├── get-started/ ① Onboarding (renamed from quick-start/)
│ ├── setup/
│ │ ├── installation.md midenup install
│ │ └── cli-basics.md first commands
│ └── your-first-smart-contract/
│ ├── create.md
│ ├── deploy.md
│ └── test.md
│
├── smart-contracts/ ② Concepts + API (local only, no ingested content)
│ ├── overview.md
│ ├── getting-started.md toolchain & project structure
│ ├── accounts/
│ │ └── ...existing concept pages...
│ ├── notes/
│ │ └── ...existing concept pages...
│ ├── transactions/
│ │ └── ...existing concept pages...
│ ├── api-reference.md
│ ├── types.md
│ ├── cross-component-calls.md
│ └── patterns.md
│
├── tools/ ③ Reference + Guides (by workflow)
│ ├── index.md overview of all tools
│ ├── development/
│ │ ├── midenup.md
│ │ ├── miden-cli.md
│ │ ├── cargo-miden.md
│ │ └── templates.md rust, frontend, masm
│ ├── testing/ local — moved from develop/tutorials/rust-compiler/
│ │ ├── mockchain.md (from testing.md)
│ │ ├── debugging.md (from debugging.md)
│ │ └── pitfalls.md (from pitfalls.md)
│ ├── clients/ ingested from miden-client repo
│ │ ├── rust-client/
│ │ └── web-client/
│ └── infrastructure/
│ ├── node-setup.md
│ ├── playground.md
│ └── explorer.md
│
├── tutorials/ ④ Entire miden-tutorials repo ingested here
│ ├── index.md (ingested)
│ ├── rust-client/ (ingested)
│ ├── web-client/ (ingested)
│ └── miden-bank/ (moved to tutorials repo, ingested back)
│ ├── index.md
│ ├── 00-project-setup.md
│ ├── ...
│ └── 08-complete-flows.md
│
├── migration/ ⑤
├── faq.md
└── glossary.md
```

---

## What Changes vs Today

| Today | After | Why |
|-------|-------|-----|
| `quick-start/` | `get-started/` | Standard naming |
| `smart-contracts/` (mixed concepts + ref) | `smart-contracts/` (concepts + API only) | Clean separation — examples live in tutorials/ |
| `develop/tutorials/` (ingested + local mixed) | `tutorials/` (all ingested from one repo) | Single source of truth, clean ingestion |
| `tools/` is 1-page stub | `tools/` comprehensive, grouped by workflow | Every tool gets a page |
| Guides in `develop/tutorials/rust-compiler/` | `tools/testing/` (local) | Testing/debugging are tool-oriented, not tutorials |
| `develop/index.md` stale version note | Deleted | Content is in proper sections now |

---

## Cross-Linking Strategy

Smart contract concept pages **cross-link** to relevant tutorials rather than embedding examples:

```
smart-contracts/accounts/overview.md
→ "See tutorials for hands-on examples:"
→ links to tutorials/rust-client/counter_contract_tutorial
→ links to tutorials/web-client/counter_contract_tutorial

smart-contracts/notes/overview.md
→ links to tutorials/rust-client/mint_consume_create_tutorial
→ links to tutorials/rust-client/custom_note_how_to

tutorials/miden-bank/00-project-setup.md
→ links to tools/development/cargo-miden
→ links to smart-contracts/getting-started

tools/testing/mockchain.md
→ links to tutorials/miden-bank (examples in context)
```

---

## Content Ownership

| Section | Owner | Source |
|---------|-------|--------|
| `get-started/` | miden-docs | Local |
| `smart-contracts/` | miden-docs | Local |
| `tools/development/` | miden-docs | Local (cargo-miden possibly ingested from compiler repo) |
| `tools/testing/` | miden-docs | Local (moved from develop/tutorials/rust-compiler/) |
| `tools/clients/` | miden-client repo | CI ingests |
| `tools/infrastructure/` | miden-docs | Local |
| `tutorials/` | miden-tutorials repo | CI ingests entire repo |
| `migration/` | miden-docs | Local |

---

## CI Pipeline Changes

### Current (deploy-docs.yml lines 180-184, cut-versions.yml lines 184-188)

```bash
if [ -d "vendor/miden-tutorials/docs/src" ]; then
mkdir -p docs/builder/develop/tutorials
cp -r vendor/miden-tutorials/docs/src/* docs/builder/develop/tutorials/
echo "Synced miden-tutorials → docs/builder/develop/tutorials"
fi
```

### After

```bash
if [ -d "vendor/miden-tutorials/docs/src" ]; then
mkdir -p docs/builder/tutorials
cp -r vendor/miden-tutorials/docs/src/* docs/builder/tutorials/
echo "Synced miden-tutorials → docs/builder/tutorials"
fi
```

That's it — one path change. No multi-target copies, no merging.

**Note**: The preservation comment on lines 151/155 about "NOT fully cleaned to preserve local tutorials" is no longer needed — `tutorials/` will be fully ingested content, and local guides move to `tools/testing/`.

---

## Implementation Phases

### Phase 1: Content moves within miden-docs
1. Rename `quick-start/` → `get-started/`
2. Move `develop/tutorials/rust-compiler/{testing,debugging,pitfalls}.md` → `tools/testing/`
3. Delete `develop/` directory (all content relocated)
4. Update cross-reference links

### Phase 2: Move miden-bank to tutorials repo
1. Move `develop/tutorials/rust-compiler/miden-bank/` → miden-tutorials repo ([tutorials#165](https://github.com/0xMiden/tutorials/issues/165))
2. Remove local miden-bank from miden-docs

### Phase 3: Update CI
1. Change ingestion path in `deploy-docs.yml` (lines 180-184)
2. Change ingestion path in `cut-versions.yml` (lines 184-188)
3. Remove preservation comments (lines 151/155 in both files)
4. Update verification output paths

### Phase 4: Cross-linking
1. Add "See tutorials" links from smart-contracts concept pages to tutorials/
2. Add "See concepts" links from tutorials back to smart-contracts/
3. Verify all internal links resolve

---

## Files to Update

### CI pipeline files
- `.github/workflows/deploy-docs.yml` (lines 151, 180-184, 198-199)
- `.github/workflows/cut-versions.yml` (lines 155, 184-188, 202-203)

### Cross-reference files (add tutorial links)
- `docs/builder/smart-contracts/index.md`
- `docs/builder/smart-contracts/overview.md`
- `docs/builder/smart-contracts/getting-started.md`
- `docs/builder/smart-contracts/patterns.md`

### Local files to move
- `docs/builder/develop/tutorials/rust-compiler/testing.md` → `docs/builder/tools/testing/mockchain.md`
- `docs/builder/develop/tutorials/rust-compiler/debugging.md` → `docs/builder/tools/testing/debugging.md`
- `docs/builder/develop/tutorials/rust-compiler/pitfalls.md` → `docs/builder/tools/testing/pitfalls.md`

### Local files to move to tutorials repo
- `docs/builder/develop/tutorials/rust-compiler/miden-bank/*` (11 files — see [tutorials#165](https://github.com/0xMiden/tutorials/issues/165))

---

## Tutorial Gaps Identified

| Gap | Description | Priority |
|-----|-------------|----------|
| **Deploy to Testnet** | Miden-bank only uses MockChain; no on-chain deployment tutorial | High |
| **Custom Notes** | Standalone tutorial for note types beyond P2ID (swap, escrow, time-locked) | Medium |
| **Oracle Pattern** | Existed in v0.12 legacy tutorials, absent from new structure | Medium |
| **Client Integration** | Guide for using `miden-client` for account management & transaction submission | High |

Issue này mô tả chi tiết việc tái cấu trúc nhiều giai đoạn cho thư mục docs/builder. Hãy bắt đầu bằng việc xem xét cấu trúc docs/builder/ hiện tại trong kho lưu trữ. Các tệp pipeline CI chính cần cập nhật là .github/workflows/deploy-docs.yml và .github/workflows/cut-versions.yml. Công việc liên quan đến việc di chuyển tệp, cập nhật liên kết chéo và phối hợp với kho lưu trữ tutorials. 'Hoàn thành' có nghĩa là cấu trúc thư mục mới đã được triển khai và tất cả các liên kết nội bộ đều được giải quyết.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.