Improve Groq fallback and agent navigation metadata

PRD.md

@@ -511,6 +511,19 @@ Preferred reading order:
 The index must remain short and must not duplicate full dependency or change
 impact data.
 
+The index project header includes separate `framework`, `projectType`, and
+`workspaceType` fields. Framework remains a detected framework such as Next.js
+or Express; project type describes the primary shape such as `node-cli`,
+`web-app`, `api-service`, or `library`; workspace type distinguishes a
+monorepo from a single package. Its deterministic summary uses package
+description and detected capabilities instead of file-count filler.
+
+`criticalFiles` is a start-here list, not an import-count leaderboard. It
+prioritizes executable entry points, CLI/feature orchestrators, and files that
+own detected flows before dependency popularity. Feature maps expose an
+ordered `sourcePriority`, while `flow` describes system actions rather than a
+second file list.
+
 ---
 
 ### `.devmap/snapshot.json`
@@ -602,13 +615,20 @@ ai/
 | `ask` | `llama-3.1-8b-instant` | Fast model for focused codebase questions |
 | `analyze` | `openai/gpt-oss-20b` | Balanced architecture interpretation |
 | `analyze --deep` | `openai/gpt-oss-120b` | Heavy cross-module reasoning |
-| Fallback | `openai/gpt-oss-20b` | Production fallback when a different primary model is unavailable |
+| `ask` fallbacks | `qwen/qwen3.6-27b` -> `llama-3.3-70b-versatile` -> `openai/gpt-oss-20b` | Preserve responsiveness while increasing reasoning capacity only when needed |
+| `analyze` fallbacks | `qwen/qwen3.6-27b` -> `llama-3.3-70b-versatile` -> `llama-3.1-8b-instant` | Keep snapshot enrichment available across model-specific limits |
+| `analyze --deep` fallbacks | `llama-3.3-70b-versatile` -> `qwen/qwen3.6-27b` -> `openai/gpt-oss-20b` | Degrade heavy reasoning gradually instead of failing immediately |
 
-If a model becomes unavailable, DevMap gracefully falls back. No raw provider errors shown to users.
+DevMap retries a rate-limited model up to three times, then advances through
+the command-specific chain. It also advances when a model is unavailable or
+returns a transient provider error. Authentication and malformed-request
+errors stop immediately. Duplicate model IDs are removed, including when a
+user-configured primary model also appears in the fallback chain. No raw
+provider errors are shown to users.
 
 Model availability changes over time. Before changing the default routing,
-verify the current Groq production model list. Preview models must not be used
-as the default for a public DevMap release.
+verify the current Groq model list and lifecycle status. Preview models must
+not be used as a primary default for a public DevMap release.
 
 ### User API Key Principle
 

docs/architecture.md

@@ -442,6 +442,24 @@ agents to read `.devmap/index.json`, open the relevant feature map, and inspect
 its `sourcePriority` files before broad repository exploration. The full
 `.devmap/snapshot.json` is used only when the lightweight maps are insufficient.
 
+The index separates technical framework detection from repository shape:
+
+```txt
+framework     -> nextjs | express | unknown
+projectType   -> node-cli | web-app | api-service | library | unknown
+workspaceType -> monorepo | single-package
+```
+
+This avoids labeling a TypeScript CLI monorepo as a fake framework while still
+giving agents an immediate mental model. Project summaries are deterministic
+and combine this classification with the primary package description and
+detected capabilities.
+
+Index `criticalFiles` are ranked for reading order: executable entry points
+first, then command/flow owners, feature owners, and finally structural
+importance. Import count remains a supporting signal rather than the primary
+definition of where an agent should start.
+
 The snapshot also stores a compact `agentInstructions` object for machine
 readers. This is intentionally small: policy fields live in JSON, while the
 human-readable workflow lives in `DEVMAP.md`.
@@ -607,15 +625,20 @@ Commands should not call provider APIs directly.
 
 MVP default model routing:
 
-| Command          | Model                     |
-| ---------------- | ------------------------- |
-| `ask`            | `llama-3.1-8b-instant`    |
-| `analyze`        | `openai/gpt-oss-20b`      |
-| `analyze --deep` | `openai/gpt-oss-120b`     |
-| Fallback         | `openai/gpt-oss-20b`      |
+| Command          | Primary                    | Ordered fallbacks |
+| ---------------- | -------------------------- | ----------------- |
+| `ask`            | `llama-3.1-8b-instant`     | `qwen/qwen3.6-27b` -> `llama-3.3-70b-versatile` -> `openai/gpt-oss-20b` |
+| `analyze`        | `openai/gpt-oss-20b`       | `qwen/qwen3.6-27b` -> `llama-3.3-70b-versatile` -> `llama-3.1-8b-instant` |
+| `analyze --deep` | `openai/gpt-oss-120b`      | `llama-3.3-70b-versatile` -> `qwen/qwen3.6-27b` -> `openai/gpt-oss-20b` |
+
+Each model receives up to three exponential-backoff retries for HTTP 429.
+After those retries, or when a model is unavailable or returns HTTP 5xx,
+DevMap advances to the next unique model. Credentials and invalid requests do
+not trigger failover. The chain is resolved before streaming emits content, so
+a fallback cannot duplicate a partially rendered answer.
 
-If a model is unavailable, DevMap should fall back gracefully.
-Only Groq production models should be used as public defaults.
+Model IDs in this table were confirmed active through the Groq model-list API
+on 2026-06-20. Recheck provider lifecycle status before publishing a release.
 
 Users can override automatic routing with `devmap config model <model>`.
 Running `devmap config model auto` restores the defaults above.
@@ -639,7 +662,7 @@ Rules:
 * streaming is an optional `AiClient` capability
 * commands fall back to regular completion for clients without streaming
 * the final reconstructed text is used for snapshot persistence and metadata
-* rate-limit retry and model fallback happen before consuming response deltas
+* rate-limit retry and ordered model fallback happen before consuming response deltas
 * `--json` never streams because stdout must contain one complete JSON document
 
 ---

docs/commands.md

@@ -138,7 +138,8 @@ devmap analyze --deep
 * Apply ignore rules
 * Detect framework
 * Detect package manager
-* Detect language
+* Detect language
+* Classify project type and workspace shape separately from framework
 * Detect routes
 * Detect API routes
 * Detect dependencies
@@ -156,6 +157,11 @@ devmap analyze --deep
 * Generate architecture overview
 * Generate `.devmap/index.json` and `.devmap/features/*.json` for agents
 * Save snapshot to `.devmap/snapshot.json`
+
+The lightweight index gives agents a concise project summary and a
+start-here-oriented `criticalFiles` list. Each feature map provides
+`sourcePriority` for reading order and behavioral `flow` steps when enough
+static evidence exists.
 
 ### Internal Flow
 
@@ -576,6 +582,17 @@ devmap config model auto
 * `analyze` uses `openai/gpt-oss-20b`
 * `analyze --deep` uses `openai/gpt-oss-120b`
 
+Automatic routing also uses ordered fallback chains:
+
+* `ask`: `qwen/qwen3.6-27b`, `llama-3.3-70b-versatile`, then `openai/gpt-oss-20b`
+* `analyze`: `qwen/qwen3.6-27b`, `llama-3.3-70b-versatile`, then `llama-3.1-8b-instant`
+* `analyze --deep`: `llama-3.3-70b-versatile`, `qwen/qwen3.6-27b`, then `openai/gpt-oss-20b`
+
+DevMap advances after model-unavailable and transient provider responses. For
+rate limits, it first retries the current model three times with exponential
+backoff. Invalid API keys stop immediately instead of wasting requests on the
+rest of the chain.
+
 The command preserves the configured provider and API key. DevMap must be
 initialized before changing the model.
 

docs/for-me-personal/DEBUG.md

@@ -999,3 +999,43 @@ serta Web Landing tanpa Authentication.
 
 Kata teknis di prompt, docs, dan detector source bukan bukti capability runtime.
 Feature attribution harus bertumpu pada struktur kode dan ownership file.
+
+---
+
+## 15. Single Groq Fallback Gagal Saat Model Kedua Terbatas
+
+**Tanggal:** 2026-06-20
+
+**Status:** Selesai.
+
+### Gejala
+
+Semua command hanya memiliki satu fallback `openai/gpt-oss-20b`. Jika primary
+dan fallback sama-sama unavailable atau terkena rate limit, DevMap langsung
+jatuh ke static output walaupun model Groq lain masih aktif.
+
+### Akar Masalah
+
+`AiCompletionRequest` hanya membawa `fallbackModel` tunggal dan `GroqClient`
+hanya mencoba fallback untuk model-unavailable. HTTP 429 yang tetap gagal
+setelah tiga retry tidak dapat berpindah model.
+
+### Solusi
+
+- Tambahkan ordered `fallbackModels` sambil mempertahankan field tunggal lama.
+- Gunakan chain berbeda untuk kebutuhan ringan, standard, dan deep analysis.
+- Izinkan failover setelah 429 retries, model-unavailable, dan HTTP 5xx.
+- Hentikan chain untuk credential dan request errors.
+- Deduplikasi primary dan fallback sebelum request dikirim.
+
+### Verifikasi
+
+Endpoint model Groq akun development mengonfirmasi seluruh model pada chain
+aktif pada 2026-06-20. Unit test mencakup completion, streaming, rate-limit
+exhaustion, deduplication, dan credential failure tanpa mengekspos API key.
+
+### Pelajaran
+
+Fallback model harus berupa strategi berurutan per workload, bukan satu model
+global. Namun error yang tidak mungkin pulih lewat pergantian model tidak boleh
+memicu request tambahan.

docs/for-me-personal/PROGRESS.md

@@ -4,6 +4,37 @@ Terakhir diperbarui: 2026-06-20
 
 ## Update 2026-06-20
 
+### Project Classification Dan Start-Here Ranking
+
+- Agent index sekarang memisahkan `framework`, `projectType`, dan
+  `workspaceType`; DevMap terdeteksi sebagai TypeScript `node-cli` monorepo
+  tanpa memalsukan framework baru.
+- Package manifest utama dipilih berdasarkan bentuk project, sehingga summary
+  CLI memakai description package CLI dan bukan statistik jumlah file.
+- Deteksi language memakai dominasi source agar sedikit file config JS tidak
+  mengubah TypeScript codebase menjadi `mixed`.
+- `criticalFiles` index memprioritaskan executable entry point, CLI
+  orchestrator, flow owner, dan feature owner sebelum importance/import count.
+- Fresh static validation menghasilkan urutan `index.ts`, `analyze.ts`, lalu
+  `projectMap.ts`; `groq.ts` tidak lagi mendahului analysis flow utama.
+- `sourcePriority` dan behavioral flow dipertahankan; keduanya sudah tersedia
+  sebelum perubahan ini dan kini memiliki regression coverage bersama.
+
+### Ordered Groq Model Fallback
+
+- Mengganti single fallback dengan chain berbeda untuk `ask`, `analyze`, dan
+  `analyze --deep`.
+- Chain memakai model Groq aktif dari Qwen, Llama Versatile, GPT-OSS, dan
+  Llama Instant sesuai kebutuhan command.
+- HTTP 429 tetap mendapat tiga exponential-backoff retry pada model aktif,
+  lalu berpindah ke model berikutnya jika limit belum pulih.
+- Model unavailable dan HTTP 5xx dapat berpindah model; error API key atau
+  request invalid berhenti langsung.
+- Resolver menghapus model duplikat dan tetap mendukung field legacy
+  `fallbackModel` untuk kompatibilitas client.
+- Model list diverifikasi melalui endpoint Groq akun development pada
+  2026-06-20 tanpa mencetak atau menyimpan API key.
+
 ### AST Analyzer Dan Agent Navigation
 
 - Menambahkan analyzer registry dengan output `FileAnalysis` yang konsisten.

docs/for-me-personal/TEST.md

@@ -52,6 +52,16 @@ Expected:
   `Follow dependency` atau salinan daftar feature files;
 - `index.json.criticalFiles` dimulai dari executable/feature entry points dan
   tidak mempromosikan type-only hub hanya karena import count;
+- project header DevMap berisi `projectType: node-cli`,
+  `workspaceType: monorepo`, dan language `typescript`, sementara framework
+  tetap `unknown` karena CLI bukan framework;
+- summary menjelaskan TypeScript monorepo, Node.js CLI, package description,
+  dan capabilities tanpa file-count filler;
+- tiga critical file pertama untuk DevMap adalah `packages/cli/src/index.ts`,
+  `packages/cli/src/commands/analyze.ts`, dan
+  `packages/cli/src/analyzers/projectMap.ts`;
+- feature map Analysis Engine memulai `sourcePriority` dari `projectMap.ts`
+  dan flow menjelaskan scan/analyze/build behavior tanpa `Follow dependency`;
 - DevMap sendiri tidak mendeteksi Authentication dari README, prompt example,
   onboarding text, atau landing page;
 - feature anchor DevMap mengarah ke `projectMap.ts`, `analyze.ts`, dan landing
@@ -194,7 +204,19 @@ Expected automatic routing:
 - `ask`: `llama-3.1-8b-instant`
 - `analyze`: `openai/gpt-oss-20b`
 - `analyze --deep`: `openai/gpt-oss-120b`
-- fallback: `openai/gpt-oss-20b`
+- `ask` fallback: Qwen 3.6 27B -> Llama 70B Versatile -> GPT-OSS 20B
+- `analyze` fallback: Qwen 3.6 27B -> Llama 70B Versatile -> Llama 8B Instant
+- deep fallback: Llama 70B Versatile -> Qwen 3.6 27B -> GPT-OSS 20B
+
+Automated expectations:
+
+- unavailable model immediately advances to the next unique model;
+- HTTP 429 performs three retries with delays `1000`, `2000`, and `4000` ms,
+  then advances to the next model;
+- HTTP 401/403 stops without trying fallback models;
+- regular completion and streaming use the same ordered chain;
+- a custom configured primary remains first and duplicate fallback IDs are
+  removed.
 
 Manual override: