faf-python-sdk 1.1.2__tar.gz → 1.3.0__tar.gz

faf_python_sdk-1.3.0/.github/workflows/testpypi.yml

@@ -0,0 +1,45 @@
+name: Publish to TestPyPI
+
+# Fires on every version tag push (e.g. `git push origin v0.1.5`).
+# Stage 1 of the publish flow: stage to TestPyPI for verification BEFORE
+# creating a GitHub Release (which then fires pypi.yml for production).
+#
+# Flow:
+#   1. git tag v0.1.5 && git push origin v0.1.5     → this workflow runs
+#   2. verify install from TestPyPI                  → manual / via verify_install.py
+#   3. gh release create v0.1.5                     → triggers pypi.yml (production)
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:  # Manual trigger
+
+jobs:
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+        # No token — uses OIDC trusted publisher configured at
+        # https://test.pypi.org/manage/project/faf-python-sdk/settings/publishing/

faf_python_sdk-1.3.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to faf-python-sdk are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [1.3.0] - 2026-09-06 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+### Added
+- `faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`,
+  Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, kept in
+  parity with the canonical TypeScript. Deterministic BETTER-shaped projection:
+  `## Setup & build` (install→build→dev ordered) · `## Run the tests` ·
+  `## Where things live` · `## Conventions` · three-tier `## Guardrails` ·
+  `## Definition of Done` · `## When stuck` · `## Security & secrets` ·
+  `## Commit & PR` · `## Stack`. Human Context (who/why marketing) is
+  intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA.
+- `faf_meta_tag(faf)`, `title_label(key)`, `slot_label(path)` — the shared
+  label + metastamp helpers, also from `src/interop`.
+- Both generators take the **raw parsed dict** (`FafFile.data.raw`) — the .faf
+  format carries top-level `commands` / `key_files` / `security` that the typed
+  model doesn't surface.
+- 17 tests, including deterministic-output and human-context-omission guards.
+
+### Fixed
+- `[tool.mypy] python_version` was `"3.9"` — rejected by modern mypy
+  (`must be 3.10 or higher`). Set to `"3.10"`.
+
+## [1.2.0] - 2026-06-16 — The Dart Edition
+
+Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
+
+### Added
+- `detect_dart_project(dir)` → `DartProject` — the SDK's first detection capability. Reads `pubspec.yaml` and classifies: Flutter app vs reusable package, Dart MCP server, Dart backend (Serverpod / Dart Frog / Shelf / …), Dart CLI, or library. Exported from `faf_sdk`.
+- `faf_sdk/dart_detection.json` — the detection KNOWLEDGE spec, vendored byte-identical from faf-cli (the single source); ships in the wheel, loaded at runtime.
+- `tests/test_dart_parity.py` — 20 shared fixtures run identically by faf-cli and this SDK; parity proven by test, not by eye.
+- `scripts/sync-dart-spec.sh` — vendor + `--check` (byte-identity) the spec & fixtures from faf-cli.
+
+### Notes
+- Mirrors faf-cli `src/detect/dart.ts` exactly (A+B hybrid). To bolster Dart support, edit the spec in faf-cli (the Truth) and re-sync. No new runtime dependencies.
+
+## [1.1.2] - 2026-04-26
+
+### Changed
+- Package description aligned with the canonical "Persistent project context for Python" framing on PyPI catalog and GitHub repo metadata.
+- README lede sharpened — leads with the value proposition and the audience (MCP server / CI validator / tool authors), no longer feature-list framing.
+
+### Added
+- `CHANGELOG.md` (this file) — versioned release history, separate from the README's "What's New" section.
+- Brand mantra `FAF defines. MD instructs. AI codes.` anchored in the README and `__init__.py` module docstring.
+
+### Notes
+No runtime code changes. Patch release to surface description alignment in the PyPI catalog and tighten positioning copy. The catalog only updates on a new publish.
+
+## [1.1.1] - 2026-04-18
+
+### Fixed
+- Tier alignment to match faf-cli v6 — clean geometric symbols, no emoji. v1.1.0 mistakenly returned emoji tiers; this patch normalizes them to plain uppercase strings (`TROPHY`, `GOLD`, `SILVER`, `BRONZE`, `GREEN`, `YELLOW`, `RED`).
+
+## [1.1.0] - 2026-03-29
+
+### Added
+- **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores.
+- `score_faf()` — Mk4 scoring with 21-slot Base or 33-slot Enterprise tiers.
+- 100% parity with `faf-wasm-sdk` (Rust) and `faf-cli` (TypeScript).
+- 88 new WJTTC championship-grade tests (concurrency, adversarial input, security).
+- Total test count: 175 (was 87).
+
+### Fixed
+- 3 crash bugs in malformed YAML and null project field handling.
+
+## [1.0.2] - earlier
+
+### Added
+- Initial public release with `parse`, `parse_file`, `stringify`, `validate`, `find_faf_file`, `find_project_root`, and the typed `FafData` model.

faf_python_sdk-1.3.0/CLAUDE.md

@@ -0,0 +1,33 @@
+<!-- faf:start -->
+<!-- faf: faf-python-sdk | Python |  | Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on -->
+<!-- faf: claim=project.faf | family=FAF -->
+
+# CLAUDE.md — faf-python-sdk
+
+## What This Is
+
+Python SDK for parsing, validating, scoring, and authoring .faf project context — the Mk4 engine + interop generators other Python FAF tools build on
+
+## Stack
+
+- **Language:** Python
+- **Backend:** Python
+- **API:** SDK (library)
+- **Runtime:** Python 3.8+
+- **Hosting:** PyPI
+- **Build:** hatchling
+- **CI/CD:** GitHub Actions
+
+## Context
+
+- **Who:** Python developers building AI tools, MCP servers, and CI pipelines
+- **What:** Parse, validate, and score FAF project DNA files with 100% Mk4 parity
+- **Why:** Universal scoring across all FAF tools — same slots, same formula, same scores
+- **Where:** PyPI (pip install faf-python-sdk)
+- **When:** Every AI session that needs project context
+- **How:** Import faf_sdk, call score_faf() or parse_file()
+
+---
+
+*STATUS: BI-SYNC ACTIVE — 2026-09-06T18:19:41.228Z*
+<!-- faf:end -->

faf_python_sdk-1.3.0/CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# Contributing
+
+Contributions are welcome. Bug fixes, doc improvements, new validators,
+new scoring tactics in `mk4`, new discovery sources — all useful.
+
+This file describes **how to land a change cleanly**.
+
+---
+
+## Setup
+
+```bash
+git clone https://github.com/Wolfe-Jam/faf-python-sdk
+cd faf-python-sdk
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+That's it. You're ready to run tests and ship a fix.
+
+---
+
+## Before opening a PR
+
+Run the full check pass:
+
+```bash
+pytest tests/ -v          # all tests must pass
+mypy faf_sdk/             # strict typing — no untyped defs
+```
+
+If both come back clean, you're good to push. PRs that don't pass tests
+will not be reviewed.
+
+---
+
+## PR conventions
+
+| Type of change | Required |
+|---|---|
+| Bug fix | A regression test that fails on the bug, passes after the fix. The test comes **with** the fix, not after. |
+| New feature | Tests for the new surface. If it touches the `.faf` format itself, see "Architecture decisions" below — the SDK doesn't extend the format unilaterally. |
+| Doc-only | No tests required. README + CHANGELOG entries still expected. |
+| Refactor | Existing tests must pass unchanged. Coverage must stay ≥ existing baseline. |
+
+`mypy faf_sdk/` must be clean. Strict mode is on (`disallow_untyped_defs = true`).
+The `[tool.mypy]` section in `pyproject.toml` is authoritative.
+
+---
+
+## Branch model
+
+- `main` is always shippable. Tagged releases come from `main`.
+- Work on feature branches. PR → squash-merge into `main`.
+- Don't open PRs against tagged commits. Tags are immutable; any
+  fix lands on `main` and gets a new tag if it's release-worthy.
+
+---
+
+## Commit messages
+
+- Imperative mood: "fix: handle empty .faf gracefully" not "fixed" / "fixes".
+- Conventional-commits prefix is appreciated but not enforced
+  (`fix:` / `feat:` / `refactor:` / `chore:` / `docs:` / `test:`).
+- Body explains the **why** when it's non-obvious. The diff explains
+  the what.
+- No marketing language in commit subjects. Commit messages are
+  technical, not promotional.
+
+---
+
+## Code style
+
+- **Names over comments.** A well-named function or variable doesn't
+  need a comment explaining what it does.
+- **WHY-comments are welcome** where the *why* isn't obvious — a
+  hidden constraint, a workaround for a specific bug, a non-obvious
+  invariant.
+- **No marketing prose in code comments.** Internal docs are
+  documentation, not pitch material.
+- Type hints on all public signatures. `disallow_untyped_defs` is on.
+- `from __future__ import annotations` at the top of any new module
+  using `|` union types — keeps Python 3.8/3.9 compatibility.
+
+---
+
+## Adding a new validator / scorer / parser
+
+The SDK's modules are deliberately narrow:
+
+| Module | Job |
+|---|---|
+| `parser` | Read `.faf` (YAML) into typed dicts |
+| `validator` | Check `.faf` against the schema |
+| `mk4` | Score `.faf` (the FAF "ECU" — championship tiers) |
+| `discovery` | Find `.faf` files in a project |
+| `types` | Shared dataclasses + protocols |
+
+When adding to one of these, **stay in lane**. A scoring change goes in
+`mk4`, not `validator`. A new file-finder goes in `discovery`. Cross-cutting
+features need a small RFC in the PR description before code lands.
+
+---
+
+## Architecture decisions
+
+The SDK has firm design rules that aren't up for debate in PRs:
+
+1. **The `.faf` format spec lives in the FAF organization, not the SDK.**
+   PRs that change parser/validator behavior to "support a new format
+   feature" before the format spec adds it will be closed. The SDK
+   *implements* the spec; it doesn't *extend* it.
+2. **MIT-licensed and dependency-light.** The SDK has one runtime
+   dependency (`pyyaml`) and that's the floor we want to defend. PRs
+   that add runtime deps need strong justification.
+3. **The SDK is the foundation other Python FAF tools build on**
+   (gemini-faf-mcp, custom MCP servers, CI validators). Breaking
+   changes to public surfaces go behind a major version bump.
+
+---
+
+## CI doctrine
+
+Two rules from the project's CI philosophy:
+
+1. **Red means real.** A red `test` job is a real, actionable failure.
+   We don't tolerate flaky tests — if a test fails intermittently,
+   that's a bug in the test, fix it before merging anything else.
+2. **Type-check is observability, not a gate.** mypy failures show up
+   but tests are the only hard gate. Type cleanup PRs are welcome but
+   never urgent.
+
+If CI goes red after a merge, the breaking change owns the
+fix — revert is on the table, no shame.
+
+---
+
+## Where to file issues
+
+[github.com/Wolfe-Jam/faf-python-sdk/issues](https://github.com/Wolfe-Jam/faf-python-sdk/issues)
+
+For security issues: don't open a public issue. Email
+**team@faf.one** with details.
+
+---
+
+## License
+
+MIT. Fork it, ship it, embed it, enjoy it.
+
+**Don't copy FAF brand. Do your own.**

{faf_python_sdk-1.1.2 → faf_python_sdk-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: faf-python-sdk
-Version: 1.1.2
+Version: 1.3.0
 Summary: Persistent project context for Python — parse, validate, and score `.faf` files. The foundation other Python FAF tools (gemini-faf-mcp, custom MCP servers, CI validators) build on. IANA-registered application/vnd.faf+yaml.
 Project-URL: Homepage, https://faf.one
 Project-URL: Documentation, https://github.com/Wolfe-Jam/faf-python-sdk
@@ -32,17 +32,46 @@ Description-Content-Type: text/markdown
 
 # faf-python-sdk
 
-**Persistent project context for Python.** Parse, validate, and score `.faf` files — the foundation other Python FAF tools build on.
+**Persistent Project Context for Python. Parse, validate, score.**
 
-If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+**FAF defines. MD instructs. AI codes.**
 
+The foundation other Python FAF tools build on. If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+
+[![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-175%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
+## What's New in v1.3.0 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+`faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`, Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, in parity with the canonical TypeScript. Deterministic BETTER-shaped projection: setup (install→build→dev ordered) · tests · layout · conventions · three-tier guardrails · definition of done · security · commit · stack. Human Context (who/why marketing) is intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA, not agent ops.
+
+```python
+from faf_sdk import parse_file, generate_agents_md
+
+faf = parse_file("project.faf")
+print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+```
+
+Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll a Markdown generator. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
+
+## What's New in v1.2.0 — The Dart Edition
+
+Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
+
+```python
+from faf_sdk import detect_dart_project
+
+d = detect_dart_project(".")
+print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
+```
+
 ## What's New in v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
@@ -175,6 +204,8 @@ root = find_project_root()
 | [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
 | [faf-cli](https://npmjs.com/package/faf-cli) | CLI | npm |
 
+If `faf-python-sdk` has been useful, consider starring the repo — it helps others find it.
+
 ## Links
 
 - **Site:** [faf.one](https://faf.one)

{faf_python_sdk-1.1.2 → faf_python_sdk-1.3.0}/README.md

@@ -1,16 +1,45 @@
 # faf-python-sdk
 
-**Persistent project context for Python.** Parse, validate, and score `.faf` files — the foundation other Python FAF tools build on.
+**Persistent Project Context for Python. Parse, validate, score.**
 
-If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+**FAF defines. MD instructs. AI codes.**
 
+The foundation other Python FAF tools build on. If you're building MCP servers, CI validators, or any Python tool that needs to understand project context, start here.
+
+[![FAF](https://mcpaas.live/badge/Wolfe-Jam/faf-python-sdk.svg)](https://builder.faf.one)
 [![PyPI](https://img.shields.io/pypi/v/faf-python-sdk?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/faf-python-sdk/)
 [![Downloads](https://img.shields.io/pypi/dm/faf-python-sdk?style=for-the-badge&color=blue)](https://pypi.org/project/faf-python-sdk/)
-[![Tests](https://img.shields.io/badge/tests-175%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
+[![Tests](https://img.shields.io/badge/tests-213%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/faf-python-sdk)
 [![IANA](https://img.shields.io/badge/IANA-registered-informational?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 
 **Media Type:** `application/vnd.faf+yaml` (IANA registered)
 
+## What's New in v1.3.0 — The Interop Edition
+
+The SDK can now author AI-context files, not just parse and score them.
+
+`faf_sdk.interop` — `generate_agents_md(faf)` and `generate_gemini_md(faf)`, Python ports of faf-cli's `src/interop/agents.ts` + `gemini.ts`, in parity with the canonical TypeScript. Deterministic BETTER-shaped projection: setup (install→build→dev ordered) · tests · layout · conventions · three-tier guardrails · definition of done · security · commit · stack. Human Context (who/why marketing) is intentionally omitted from AGENTS.md — it belongs in the README / .faf DNA, not agent ops.
+
+```python
+from faf_sdk import parse_file, generate_agents_md
+
+faf = parse_file("project.faf")
+print(generate_agents_md(faf.data.raw))   # takes the raw dict — carries top-level commands / key_files / security
+```
+
+Any Python FAF tool that authors an AI-context file wraps this now — never hand-roll a Markdown generator. `gemini-faf-mcp` 2.7.0's `faf_agents` / `faf_gemini` are the reference wrappers.
+
+## What's New in v1.2.0 — The Dart Edition
+
+Adds `detect_dart_project()`: content-aware Dart/Flutter detection from a `pubspec.yaml` (Flutter app vs package · Dart MCP / backend / CLI / library), reproducing faf-cli's engine byte-for-byte — 20 shared fixtures, parity-tested.
+
+```python
+from faf_sdk import detect_dart_project
+
+d = detect_dart_project(".")
+print(d.app_type, d.framework)   # e.g. "mobile" "Flutter"
+```
+
 ## What's New in v1.1.0
 
 **Mk4 Championship Scoring Engine** — the same 33-slot scoring algorithm used by the Rust compiler and TypeScript CLI, now in Python. Same slots, same formula, same scores. Every FAF tool in every language now agrees on what 100% means.
@@ -143,6 +172,8 @@ root = find_project_root()
 | [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
 | [faf-cli](https://npmjs.com/package/faf-cli) | CLI | npm |
 
+If `faf-python-sdk` has been useful, consider starring the repo — it helps others find it.
+
 ## Links
 
 - **Site:** [faf.one](https://faf.one)

{faf_python_sdk-1.1.2 → faf_python_sdk-1.3.0}/faf_sdk/__init__.py

@@ -24,6 +24,8 @@ from .parser import parse, parse_file, stringify, FafFile
 from .validator import validate, ValidationResult
 from .mk4 import score_faf, Mk4Result, SlotState, LicenseTier
 from .discovery import find_faf_file, find_project_root, load_fafignore
+from .detect import detect_dart_project, DartProject
+from .interop import generate_agents_md, generate_gemini_md, faf_meta_tag
 from .types import (
     FafData,
     ProjectInfo,
@@ -34,7 +36,7 @@ from .types import (
     AIScoring
 )
 
-__version__ = "1.1.2"
+__version__ = "1.3.0"
 __all__ = [
     # Parser
     "parse",
@@ -53,6 +55,13 @@ __all__ = [
     "find_faf_file",
     "find_project_root",
     "load_fafignore",
+    # Detection (Dart/Flutter — A+B hybrid, parity with faf-cli)
+    "detect_dart_project",
+    "DartProject",
+    # Interop — AGENTS.md / GEMINI.md generators (parity with faf-cli src/interop)
+    "generate_agents_md",
+    "generate_gemini_md",
+    "faf_meta_tag",
     # Types
     "FafData",
     "ProjectInfo",

faf_python_sdk-1.3.0/faf_sdk/dart_detection.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "_doc": "SINGLE SOURCE of Dart/Flutter detection KNOWLEDGE (A+B hybrid, the Truth-is-faf-cli spec). faf-cli imports this directly; faf-python-sdk vendors a synced copy (phase 2); MCPs consume the SDK (phase 3). To bolster Dart/Flutter support — a new state library, server framework, MCP dep — edit THIS file and every engine inherits it. The thin per-language LOGIC (pubspec parse, app-vs-package heuristic, priority branching) lives in code, not here.",
+  "flutterDeps": ["flutter"],
+  "mcpDeps": ["dart_mcp", "mcp_server", "mcp_dart", "dart_mcp_server", "mcp"],
+  "serverFrameworks": [
+    ["serverpod", "Serverpod"],
+    ["dart_frog", "Dart Frog"],
+    ["conduit", "Conduit"],
+    ["angel3_framework", "Angel3"],
+    ["alfred", "Alfred"],
+    ["shelf", "Shelf"]
+  ],
+  "stateManagement": [
+    ["flutter_riverpod", "Riverpod"],
+    ["hooks_riverpod", "Riverpod"],
+    ["riverpod", "Riverpod"],
+    ["flutter_bloc", "Bloc"],
+    ["bloc", "Bloc"],
+    ["provider", "Provider"],
+    ["get", "GetX"],
+    ["flutter_mobx", "MobX"],
+    ["mobx", "MobX"],
+    ["signals", "Signals"]
+  ],
+  "routing": [
+    ["go_router", "go_router"],
+    ["auto_route", "auto_route"]
+  ]
+}

faf_python_sdk-1.3.0/faf_sdk/detect.py

@@ -0,0 +1,167 @@
+"""
+Dart/Flutter detection — CONTENT-AWARE pubspec classification (Python).
+
+PARITY: this mirrors faf-cli src/detect/dart.ts EXACTLY. A pubspec.yaml alone
+does NOT mean Flutter — the same manifest backs Flutter apps, pure-Dart CLIs,
+packages, servers (Dart Frog / Shelf / Serverpod) and MCP servers
+(dart_mcp / mcp_server). We read the dependencies and branch.
+
+The detection KNOWLEDGE (which deps mean what) lives in dart_detection.json —
+a byte-identical, synced copy of faf-cli's src/detect/dart-detection.json (the
+single source, A+B hybrid). To bolster Dart support, edit the spec in faf-cli
+(the Truth) and re-run scripts/sync-dart-spec.sh. The thin per-language LOGIC
+(pubspec parse, app-vs-package heuristic, priority branching) lives here.
+
+Behavior parity with faf-cli is PROVEN by tests/test_dart_parity.py, which runs
+the SAME shared fixtures faf-cli runs in tests/detect/dart-parity.test.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+_SPEC: Dict[str, Any] = json.loads(
+    (Path(__file__).parent / "dart_detection.json").read_text(encoding="utf-8")
+)
+
+# Detection KNOWLEDGE — sourced from dart_detection.json, never hand-listed here.
+FLUTTER_DEPS: List[str] = list(_SPEC["flutterDeps"])
+MCP_DEPS: List[str] = list(_SPEC["mcpDeps"])
+SERVER_FRAMEWORKS: List[List[str]] = [list(e) for e in _SPEC["serverFrameworks"]]
+STATE_MGMT: List[List[str]] = [list(e) for e in _SPEC["stateManagement"]]
+ROUTING: List[List[str]] = [list(e) for e in _SPEC["routing"]]
+
+
+@dataclass
+class DartProject:
+    """Classification of a Dart/Flutter project from its pubspec.yaml."""
+
+    app_type: str  # 'mobile' | 'mcp' | 'backend' | 'cli' | 'library'
+    is_flutter: bool
+    framework: str  # 'Flutter' | 'Dart Frog' | 'Serverpod' | 'Shelf' | ... | ''
+    state_management: str  # 'Riverpod' | 'Bloc' | 'Provider' | 'GetX' | ... | ''
+    routing: str  # 'go_router' | 'auto_route' | ''
+    testing: str  # 'flutter_test' | 'test' | ''
+    found: str  # human-readable rationale for the .faf `# found:` comment
+
+    def to_dict(self) -> Dict[str, object]:
+        """Project to the faf-cli DartProject shape (camelCase) for parity checks."""
+        return {
+            "appType": self.app_type,
+            "isFlutter": self.is_flutter,
+            "framework": self.framework,
+            "stateManagement": self.state_management,
+            "routing": self.routing,
+            "testing": self.testing,
+            "found": self.found,
+        }
+
+
+def _pubspec_deps(content: str) -> Set[str]:
+    """Collect dependency names from dependencies / dev_dependencies sections."""
+    deps: Set[str] = set()
+    in_deps = False
+    for line in content.split("\n"):
+        if re.match(r"^(dependencies|dev_dependencies|dependency_overrides):\s*$", line):
+            in_deps = True
+            continue
+        # A new top-level key (no leading whitespace) ends the dependency section.
+        if re.match(r"^\S", line):
+            in_deps = False
+        if in_deps:
+            m = re.match(r"^\s{2}([a-zA-Z0-9_]+):", line)
+            if m:
+                deps.add(m.group(1).lower())
+    return deps
+
+
+def detect_dart_project(directory: str) -> Optional[DartProject]:
+    """Classify a Dart/Flutter project from its pubspec.yaml. None if not Dart."""
+    path = Path(directory) / "pubspec.yaml"
+    if not path.exists():
+        return None
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    deps = _pubspec_deps(content)
+
+    def has(dep: str) -> bool:
+        return dep.lower() in deps
+
+    # Flutter: the `flutter` SDK dep, a top-level `flutter:` section, or `sdk: flutter`.
+    is_flutter = (
+        any(has(d) for d in FLUTTER_DEPS)
+        or re.search(r"^flutter:\s*$", content, re.MULTILINE) is not None
+        or re.search(r"\bsdk:\s*flutter\b", content) is not None
+    )
+
+    mcp_dep = next((d for d in MCP_DEPS if has(d)), None)
+    server = next((e for e in SERVER_FRAMEWORKS if has(e[0])), None)
+    state_entry = next((e for e in STATE_MGMT if has(e[0])), None)
+    state_management = state_entry[1] if state_entry else ""
+    route_entry = next((e for e in ROUTING if has(e[0])), None)
+    routing = route_entry[1] if route_entry else ""
+    testing = "flutter_test" if has("flutter_test") else ("test" if has("test") else "")
+
+    # CLI: a top-level `executables:` section, or bin/*.dart entry points.
+    has_executables = re.search(r"^executables:\s*$", content, re.MULTILINE) is not None
+    has_bin_dart = False
+    bin_dir = Path(directory) / "bin"
+    if bin_dir.is_dir():
+        try:
+            has_bin_dart = any(f.endswith(".dart") for f in os.listdir(bin_dir))
+        except OSError:
+            has_bin_dart = False
+    is_cli = has_executables or has_bin_dart
+
+    framework = ""
+    app_type: str
+    found: str
+
+    if is_flutter:
+        framework = "Flutter"
+        # App vs package: an app has lib/main.dart (the entry) or `publish_to: none`;
+        # a reusable Flutter package has neither — it's publishable, lib/ exports only.
+        is_app = (Path(directory) / "lib" / "main.dart").exists() or (
+            re.search(r"^publish_to:\s*['\"]?none\b", content, re.MULTILINE) is not None
+        )
+        if is_app:
+            app_type = "mobile"
+            found = "pubspec.yaml (Flutter app)"
+        else:
+            app_type = "library"
+            found = "pubspec.yaml (Flutter package)"
+    elif mcp_dep:
+        app_type = "mcp"
+        found = f"pubspec.yaml + {mcp_dep} (Dart MCP server)"
+    elif server:
+        app_type = "backend"
+        framework = server[1]
+        found = f"pubspec.yaml + {server[0]} (Dart backend)"
+    elif is_cli:
+        app_type = "cli"
+        found = (
+            "pubspec.yaml executables: (Dart CLI)"
+            if has_executables
+            else "pubspec.yaml + bin/*.dart (Dart CLI)"
+        )
+    else:
+        app_type = "library"
+        found = "pubspec.yaml (Dart package)"
+
+    return DartProject(
+        app_type=app_type,
+        is_flutter=is_flutter,
+        framework=framework,
+        state_management=state_management,
+        routing=routing,
+        testing=testing,
+        found=found,
+    )