Crab-Archi-Design

# Crab Archi Design Crab Archi Design is an original-SVG-first framework for architectural community layout design automation. ## Public Browser Canvas Open the [public canvas](https://crab-archi-design.vercel.app/). The public canvas runs the same Python SVG editing engine inside each visitor's browser. Import a drawing, edit native elements, mark protected zones, measure, undo/redo, review in 3D, and download the edited SVG and design-request JSON. Drawings stay in the browser. Codex/OpenCrab-driven redesign and DWG conversion require the local CLI/MCP studio; the public site does not claim to run them. See [public release and deployment](docs/public_release.md) for supported SVGs, verified fixes, the OpenCrab handoff, and the static deployment boundary. OpenCrab is a required part of the workflow, not an optional reference layer. - OpenCrab homepage: https://opencrab.sh - OpenCrab dashboard: https://opencrab.sh/dashboard - OpenCrab desktop: https://opencrab.sh/desktop It is designed around the workflow proven in the Community SVG experiments: 1. Start from an original SVG drawing. 2. Recognize drawing elements, program labels, protected structures, and mutable zones. 3. Query OpenCrab MCP for the installed ontology pack, source evidence, topology, adjacency, and reusable design claims. 4. Attach standards from Excel, CSV, PDF, or ontology evidence. 5. Build a target topology manifest that links labels, room envelopes, protected geometry, standards, evidence, and constraints. 6. Compile design direction into structured intent JSON. 7. Generate native SVG alternatives with a deterministic geometry engine. 8. Let users revise alternatives by natural language or doodle sketch. 9. Run QA gates before exporting the final native SVG. The framework intentionally keeps LLMs out of direct SVG mutation. Codex or another LLM should produce `DesignIntent` and `EditIntent` JSON. A deterministic solver should apply safe native SVG patches. ## CrabCADParser: DWG/DXF to OpenCrab The repository also includes [CrabCADParser](docs/crabcadparser.md), a local Crab-style GUI/CLI/MCP bridge that scans a DWG/DXF directory, preserves reconstructable CAD IR v2, extracts CAD evidence and architectural role hints, and builds an OpenCrab Pack v1 bundle. DXF is parsed directly; DWG uses an optional local ODA File Converter. The generated `opencrab/ingest_payloads.jsonl` is intentionally explicit and reviewable before an OpenCrab MCP client submits it. ```bash .venv/bin/crabcadparser gui # or .venv/bin/crabcadparser run /path/to/cad-source --output-dir /path/to/cad-source_crabcadparser --max-files 10 # replay structured IR to a new DXF .venv/bin/crabcadparser reconstruct /path/to/documents/cad-document_xxx.json /path/to/reconstructed.dxf --report /path/to/roundtrip.json ``` See [docs/crabcadparser.md](docs/crabcadparser.md) for the pack contract, MCP tools, QA gates, and DWG setup. ## OpenCrab MCP Contract Every production project must use OpenCrab MCP before writing a design alternative: 1. Read the target drawing recognition IR. 2. Ask OpenCrab MCP for the relevant ontology pack and evidence-backed topology. 3. Map superior-case topology onto the target drawing's protected and mutable zones. 4. Compile an evidence-cited design intent. 5. Let the deterministic SVG solver generate only native SVG geometry. 6. Reject any candidate that violates parking, core, column, ramp, egress, or community shell constraints. See [docs/opencrab_mcp_workflow.md](docs/opencrab_mcp_workflow.md) for the required pack and topology flow. ## Install Python 3.9+ is supported. ```bash pip install -e . ``` ## Quickstart Run the complete sample path from job creation to final release audit: ```bash examples/run_quickstart.sh ``` The script creates a sample job spec, Markdown review brief, validated project package, and `release_audit_###.json` under `.quickstart-projects/`. ## CI Preflight GitHub Actions runs the same core contract used by local handoff: 1. Install `crab-archi-design` with test dependencies. 2. Compile the CLI and reference engine. 3. Run the Python test suite. 4. Check the stdio MCP entry point with `crab-archi-design-mcp --help`. 5. Generate the MCP/OAuth exec manifest with `mcp-manifest`. 6. Generate MCP client and OAuth worker runtime config with `mcp-config`. 7. Verify the generated MCP runtime with `mcp-smoke`. 8. Generate a JSON job spec and Markdown review brief with `create-job --validate --strict-validation --brief`. 9. Validate the JSON job spec with `validate-job --strict`. 10. Execute `run-job` from a JSON job spec for the SaaS/OAuth path. 11. Execute `workflow-run` with sample SVG, standards, constraints, and OpenCrab MCP evidence. 12. Execute the production `workflow-run --strict` and `revision-run --strict` path with `same-layer-svg-engine`, explicit scale calibration, program relabels, wall openings, and endpoint moves, then release-audit the result. 13. Execute `revision-run` on the same project to verify the repeat-edit path. 14. Run `recognition-audit` when a target drawing needs a recognition-first gate before mutation. 15. Run `export-package`, `verify-package --strict`, `doctor --strict`, and `release-audit --strict`. The CI sample uses: - `examples/original_sample.svg` - `examples/area_standard_sample.csv` - `examples/constraint_sketch_sample.json` - `examples/opencrab_mcp_result_sample.json` - `examples/job_spec_sample.json` - `examples/run_quickstart.sh` ## CLI ```bash crab-archi-design init \ --project-id demo \ --source-svg /path/to/original.svg \ --households 900 \ --standards /path/to/area_standard.xlsx \ --ontology-pack community_svg_topology_ontology_v2 \ --opencrab-mcp-server opencrab \ --engine-adapter layout-svg-engine crab-archi-design workflow-run \ --project-id demo \ --source-svg /path/to/original.svg \ --households 900 \ --standards examples/area_standard_sample.csv \ --ontology-pack community_svg_topology_ontology_v2 \ --opencrab-result-file /path/to/opencrab_mcp_result.json \ --constraint-sketch examples/constraint_sketch_sample.json \ --scale-mm-per-world 30 \ --scale-evidence "User-confirmed grid dimension." \ --prompt "Open the greenery lounge more toward the main hall and keep parking/core locked." \ --engine-adapter same-layer-svg-engine \ --engine-arg=--apply-program-relabels \ --engine-arg=--apply-openings \ --engine-arg=--apply-endpoint-moves \ --skip-preview \ --strict crab-archi-design revision-run \ --project-id demo \ --text "Tighten the golf and sauna adjacency while keeping screen golf inside the golf cluster." \ --sketch examples/sketch_layer_sample.json \ --skip-preview crab-archi-design create-job \ --project-id demo-job \ --source-svg examples/original_sample.svg \ --households 900 \ --standards examples/area_standard_sample.csv \ --ontology-pack community_svg_topology_ontology_v2 \ --opencrab-result-file examples/opencrab_mcp_result_sample.json \ --constraint-sketch examples/constraint_sketch_sample.json \ --prompt "Improve the greenery lounge hierarchy while preserving protected geometry." \ --engine-adapter layout-svg-engine \ --output job_specs/demo-job.json \ --validate \ --strict-validation \ --skip-preview \ --brief crab-archi-design validate-job \ --job job_specs/demo-job.json \ --strict crab-archi-design run-job \ --job job_specs/demo-job.json \ --strict crab-archi-design recognize-svg \ --project-id demo crab-archi-design recognize-svg-v2 \ --project-id demo crab-archi-design standards-attach \ --project-id demo \ --file examples/area_standard_sample.csv \ --households 900 crab-archi-design scale-attach \ --project-id demo \ --known-mm 8400 \ --known-world-length 100 \ --evidence "User-confirmed grid dimension." crab-archi-design evidence-attach \ --project-id demo \ --source localcrab \ --pack-id community_svg_topology_ontology_v2 \ --summary "OpenCrab/LocalCrab verified the precedent topology, evidence chunks, protected zones, and 900-household program targets." crab-archi-design opencrab-request \ --project-id demo \ --intent "Find evidence-backed precedent topology for the target community layout." \ --max-results 8 crab-archi-design opencrab-sync \ --project-id demo \ --result-file /path/to/opencrab_mcp_result.json \ --source-tool opencrab_search_documents crab-archi-design constraint-attach \ --project-id demo \ --sketch examples/constraint_sketch_sample.json crab-archi-design topology-build \ --project-id demo crab-archi-design prompt-edit \ --project-id demo \ --text "Open the greenery lounge more toward the main hall and keep parking/core locked." crab-archi-design sketch-intent \ --project-id demo \ --sketch examples/sketch_layer_sample.json crab-archi-design doodle-editor ./studio.sh # one-command studio launcher (installs .venv on first run) ./canvas.sh 8770 examples/original_sample.svg # live SVG CAD canvas + agent MCP # then: claude mcp add crab-canvas -- .venv/bin/crab-archi-design-canvas-mcp --port 8770 # see docs/live_canvas.md crab-archi-design studio \ --project-root projects \ --port 8765 \ --open crab-archi-design edit-brief \ --project-id demo \ --intent all crab-archi-design project-status \ --project-id demo crab-archi-design design-handoff \ --project-id demo \ --intent all \ --task "Prepare a native SVG community layout alternative." crab-archi-design apply-edit \ --project-id demo \ --intent all \ --skip-preview crab-archi-design review-panel \ --project-id demo crab-archi-design export-package \ --project-id demo \ --include-source-svg crab-archi-design verify-package \ --zip projects/demo/exports/demo_export_001.zip \ --strict crab-archi-design doctor \ --project-id demo \ --zip projects/demo/exports/demo_export_001.zip \ --strict crab-archi-design release-audit \ --project-id demo \ --zip projects/demo/exports/demo_export_001.zip \ --strict crab-archi-design mcp-manifest \ --output integrations/crab_archi_design_mcp_manifest.json crab-archi-design mcp-config \ --output integrations/crab_archi_design_mcp_config.json \ --project-root projects crab-archi-design mcp-smoke \ --config integrations/crab_archi_design_mcp_config.json \ --strict crab-archi-design-mcp --stdio crab-archi-design qa --project-id demo ``` `create-job` writes a `crab-archi-design-job-spec-v1` file from CLI, MCP, OAuth, or SaaS upload inputs. It accepts the original SVG, standards, OpenCrab MCP result files, doodle constraints, prompt, engine adapter, export policy, and optional validation flags, then prints the job spec path as the first stdout line. Use `--validate --strict-validation` to fail fast before `run-job`, and `--brief` to write a Markdown review brief next to the job spec. `validate-job` checks a `crab-archi-design-job-spec-v1` file before execution. It verifies required project inputs, source SVG, standards, OpenCrab/evidence input, constraint sketch, engine adapter, ontology pack, and referenced local file paths, then writes `diagnostics/job_validation_###.json`. `run-job` is the SaaS/OAuth/MCP worker entry point. It reads a validated `crab-archi-design-job-spec-v1` JSON file containing the source SVG path, standards, OpenCrab MCP result files, doodle constraints, natural-language prompt, engine adapter, and export/verification policy. It then runs `workflow-run`, `export-package`, `verify-package`, and `doctor`, and writes a `projects/<project>/jobs/job_run_###.json` report. `workflow-run` executes the normal project path in one command: init if needed, recognize source SVG, build Recognition IR v2 with source document indexes, attach standards, sync or attach evidence, attach constraints, build topology, optionally attach an explicit scale calibration (`--scale-mm-per-world` or `--scale-known-mm` with `--scale-known-world-length`), create prompt/sketch intents, write the edit brief, status, design handoff, apply edit, review panel, final status, and a `projects/<project>/workflow/workflow_run_###.json` report. When the engine adapter is `same-layer-svg-engine`, workflow-run automatically runs `recognition-audit` and `svg-patch-plan` after topology, so the production mutation path never starts from a stale or missing patch plan. With `--strict`, workflow-run exits non-zero unless the final status is `pass`, which makes it usable as a CI gate. `revision-run` executes the repeat-edit path for an existing project. It can attach an updated constraint sketch, rebuild topology, convert natural language and/or doodle sketches into edit intents, regenerate the edit brief and handoff, run the engine, create a review panel, and write `projects/<project>/revisions/revision_run_###.json`. For `same-layer-svg-engine` projects it also re-runs `recognition-audit` and rebuilds the `svg-patch-plan` after topology, so every revision mutates against a fresh candidate plan. `--strict` exits non-zero unless the revision status is `pass`. `apply-edit` reads structured natural-language and doodle intents plus recognition, topology, evidence, standards, and constraints, writes a `solver_input.json`, runs the configured engine adapter, copies the resulting native SVG into `projects/<project>/alternatives/`, and writes an `apply_edit_report.json`. The report includes `candidate_quality`, which classifies apply checks and engine gates into hard constraints such as native-SVG-only output, shell/no-go/protected geometry preservation, and soft design quality checks such as coverage, aspect efficiency, program hierarchy, openings, and circulation detail. `svg-patch-plan` writes `projects/<project>/patch_plans/svg_patch_plan_###.json`. It is the preferred bridge from recognition into real SVG editing: when Recognition IR v2 is active it uses IR v2 geometry and source document indexes as the production candidate source, identifies existing source SVG elements by element index/tag/bbox, separates mutable wall/room candidates from locked geometry, creates same-layer opening candidates for line/path splitting, creates topology-aware endpoint-move candidates for existing line/polyline/path grip edits, anchors edits to existing program labels, and explicitly disallows zoning overlay generation. `<use>`-expanded primitives can inform recognition, but non-editable instances are kept out of same-layer mutation candidates. When topology contains wall-bounded `space_region` and `program_cluster` nodes, the plan prioritizes existing SVG elements that intersect those clusters so edits target the recognized original spaces first. Opening and endpoint-move candidates are scored by OpenCrab `ontology_cluster_adjacency_target` edges, so relationships such as greenery lounge to main hall are carried as evidence-backed mutation metadata instead of freehand redrawing. The plan also embeds a deterministic solver objective report from the split `solver.sizing`, `solver.feasible`, `solver.placement`, `solver.localsearch`, `solver.scale`, and `solver.objective` modules: standards are parsed into role-level target areas, mutable/shell/protected regions are summarized, initial program placement seeds are generated inside the mutable-zone bbox, OpenCrab adjacency targets are scored and locally improved, and the final local-search program order is projected back into mutable candidate priority before same-layer SVG mutation. Explicit scale manifests or consistent dimension-text-to-segment pairs can calibrate architectural scale, and target roles are matched against recognized program clusters before any SVG mutation. If scale evidence is weak, the report stays `review_required` instead of pretending SVG paper units are architectural area. Production redraw engines should consume this plan and mutate existing SVG elements in place. `same-layer-svg-engine` is the first built-in native geometry patch adapter for that production path. It consumes the latest `svg-patch-plan`, addresses existing source SVG elements by document index, collapses mutable internal partition lines, polylines, and open single-subpath M/L/H/V paths to zero length, and marks them removed in the same layer while preserving original geometry in `data-crab-original-*` attributes. With `--engine-arg=--apply-program-relabels`, it also rewrites existing text labels in place, such as `작은도서관` to `그리너리 라운지`, so the candidate records a visible semantic design change without adding an overlay label layer. With `--engine-arg=--apply-openings`, it splits selected wall lines, polylines, and open single-subpath M/L/H/V paths into before/after same-parent segments to create door openings, converting transformed polyline/path openings through world length and back into local `points`/`d` coordinates before writing. With `--engine-arg=--apply-endpoint-moves`, it moves existing line/polyline endpoints and open single-subpath M/L/H/V path endpoints by explicit world-coordinate `x/y` or `dx/dy` values, converts those values through any accumulated SVG transform back into the element's local attribute coordinates, and preserves the original coordinates in reversible attributes. Curved, arc, and closed paths are skipped for review instead of being approximated. Its QA report snapshots locked/protected candidates before mutation, skips any mutation candidate that targets a locked element, fails `locked_targets_not_selected` for that patch-plan conflict, and fails `locked_geometry_unchanged` if any protected element changes. It does not add a zoning overlay group, image, or redraw layer. At execution time, `same-layer-svg-engine` also projects the current `solver_input.intents` onto the latest patch plan before selecting candidates. That means a prompt or doodle revision created after `svg-patch-plan` can still re-rank same-layer wall removals, openings, and endpoint moves by target role without asking an LLM to write coordinates. Opening and endpoint candidates may come from recognized program clusters or from `solver_projected_role` metadata. This lets the engine use topology-improved solver roles for existing SVG lines even when the original room-cluster recognition is incomplete. The engine summary includes `intent_role_coverage`, listing requested target roles, touched roles, covered roles, missing roles, and coverage ratio. This gives the revision loop a concrete signal when, for example, greenery, fitness, and golf were touched but sauna still needs a follow-up pass. If any requested role is missing, `intent_repair_recommendations` reports the remaining candidate pool for that role and a suggested edit intent for the next bounded revision. The low-level CAD-like primitive edits used by this adapter live in `solver/svg_edit_ops.py`: same-parent line/path opening splits, transform-aware path opening conversion, endpoint grip edits, source-attribute preservation, native element counting, and per-element edit capability reports. `solver/svg_mutation.py` remains the orchestration layer for candidate selection, protected-target skips, locked geometry preservation, and mutation summary reporting. The same capability checks gate opening and endpoint mutations before geometry is touched, and engine summaries include `edit_capability_summary`, `edit_capability_totals`, and review-count QA gates so unsupported primitives such as closed paths, curved paths, or non-invertible endpoint transforms are surfaced as `review_required` instead of silently degrading into overlay-style redraws. Engine adapter execution is allowlisted by default. Built-in aliases for `reference-svg-engine`, `layout-svg-engine`, and `same-layer-svg-engine` may run directly; custom local adapters are refused unless a trusted local CLI user explicitly passes `--allow-custom-engine`. MCP `raw_args` cannot enable that escape hatch, so OAuth/SaaS wrappers stay on the deterministic built-in engine path unless they deliberately write a trusted local job spec outside the MCP raw-argument channel. `layout-svg-engine` is the built-in redraw adapter. By default it can create a standards-backed native SVG room-envelope candidate on top of the source drawing; with `--engine-arg=--standalone-redraw` it writes a clean CAD-style SVG candidate without copying source linework, using the source only for viewBox, recognition evidence, shell/no-go constraints, columns, standards rows, and OpenCrab-backed intent. The standalone path is the studio default because it avoids the brittle behavior of trying to patch poorly recognized legacy SVG walls one segment at a time. `reference-svg-engine` remains available as a diagnostic adapter. It consumes the same solver input and emits a native SVG candidate plus engine report, using only additive SVG elements and no raster overlay. `recognize-svg` writes `projects/<project>/recognition/recognition_manifest.json`. It stores SVG parse status, viewBox, primitive counts, primitive bounding boxes, column candidates, wall candidates, room-envelope candidates, label candidates, and program role hints before any layout mutation. `recognize-svg-v2` writes `projects/<project>/recognition/recognition_ir_v2.json`. It uses the modular parser stack (`safe_load`, `namespace`, `defs`, `style`, `units`, `transform`, `shapes`, `path`, `geometry`, `recognition/classify`) to normalize SVG primitives into world coordinates. This path records physical document scale metadata from width/height/viewBox (`unit_scale_x_mm`, `unit_scale_y_mm`, and consistency), attaches deterministic node-level physical metrics (`bbox_mm`, `area_mm2`, `area_m2`, `perimeter_mm`) when scale is available, skips raw `<defs>` geometry, expands placed `<use>`/`<symbol>` instances into their actual drawing coordinates, supports nested affine transforms including skew, applies a deterministic tag/class/id stylesheet cascade plus presentation and inline styles, flattens line, cubic, quadratic, and elliptical arc path geometry for recognition, and keeps labels, raster detection, and role hints in a single IR instead of asking an LLM to redraw geometry. `topology-build` writes `projects/<project>/topology/topology_manifest.json`. It turns recognition candidates, standards rows, OpenCrab evidence, and doodle constraints into an explicit node/edge graph for labels, room envelopes, columns, walls, program standards, protected constraints, and ontology adjacency targets. When `recognition_ir_v2.json` exists and is active, topology uses it as the preferred recognition source so path geometry, transform-normalized labels, source document indexes, and column candidates become graph nodes. It also creates `space_region` nodes when a label can be bounded by nearby wall axes; these are recognition evidence for existing program spaces, not a generated zoning overlay. `qa`, `edit-brief`, `project-status`, `design-handoff`, and `apply-edit` require this manifest to be active before a final SVG alternative can pass. `recognition-audit` writes `projects/<project>/audits/recognition_audit_###.json`. It is the recognition-first gate for real architectural drawings: program labels must have coordinates, wall and column candidates must be detected, Recognition IR v2 must provide source document indexes for CAD-like same-layer mutation, the community shell/mutable zone/protected no-go zones must be confirmed, and topology must connect labels to room envelopes or wall-bounded `space_region` nodes. The audit reads IR v2 metrics first when available, falling back to the legacy recognition manifest for older project summaries; production mutation readiness requires the v2 source-index gate. If this audit is `review_required`, the correct next step is to improve recognition or user-confirmed constraints, not to generate another zoning block. `standards-attach` writes `projects/<project>/standards/standards_manifest.json`. CSV files are parsed into selected rows for the household count; Excel, PDF, and JSON files are attached as verified standards references for the engine adapter. `scale-attach` writes `projects/<project>/scale/scale_manifest.json`. Use it when OCR, a verified dimension string, or a user-confirmed measurement provides architectural scale that the SVG parser cannot infer safely from vectorized dimension text. It accepts either `--mm-per-world` or `--known-mm` with `--known-world-length`; `svg-patch-plan` gives this manifest priority over automatic dimension-text inference and records the selected scale in `solver_objective.scale_calibration`. `evidence-attach` writes `projects/<project>/evidence/evidence_manifest.json`. `qa` and `apply-edit` require this manifest to be verified before a final SVG alternative can pass. `opencrab-sync` normalizes JSON returned by OpenCrab MCP tools such as `opencrab_query` and `opencrab_search_documents`. It writes `projects/<project>/opencrab/opencrab_sync_###.json` and appends the normalized evidence to `projects/<project>/evidence/evidence_manifest.json`. `opencrab-request` writes `projects/<project>/opencrab/opencrab_request_###.json` and `.md`. It packages the recommended OpenCrab MCP tool call, query, expected result file, and next `opencrab-sync` command from the current project context. `constraint-attach` writes `projects/<project>/constraints/constraint_manifest.json`. Use it for community shell, parking/core/column/ramp no-go edges, lock boundaries, mutable zones, and projectable zones. `qa` and `apply-edit` require an active constraint manifest before a final SVG alternative can pass. `./studio.sh [port]` creates or finds `.venv`, installs the package on first run, and opens the local studio at `http://127.0.0.1:<port>/`. Confirm the community shell and provide a design prompt. New projects require an actual OpenCrab MCP result file. Missing boundaries block the run; the whole drawing is never implicitly treated as editable. The shell polygon is preserved without centroid scaling. Review derived constraints before accepting a design result. The default experimental engine is `layout-svg-engine --standalone-redraw`. Strict CLI gates apply, but a passing run is not architectural design approval. Reports are written to `projects/<project>/studio/studio_run_###/`. The HTTP API (`/api/load-svg`, `/api/run`, `/api/artifact`, `/api/status`) is also available to local agents. Use the public browser canvas for manual native SVG editing and a Codex/OpenCrab JSON handoff. The local server binds to 127.0.0.1. `doodle-editor` prints the local SVG doodle editor path and `file://` URL. The editor loads a source SVG from your machine, records vector strokes in source viewBox coordinates, and downloads sketch JSON for `sketch-intent`. `edit-brief` summarizes natural-language and doodle intents before SVG mutation. It writes JSON and Markdown briefs, checks OpenCrab evidence, and flags doodle strokes outside the source SVG viewBox. `project-status` writes `projects/<project>/status/project_status.json`. It summarizes readiness gates, latest briefs, latest apply reports, latest alternatives, latest review panels, and metrics such as recognized primitive count, program labels, topology nodes/edges, evidence count, standards rows, constraints, and edit intents. `design-handoff` writes `projects/<project>/handoffs/design_handoff_###.json` and `.md`. It packages the current status gates, source recognition, topology graph summary, OpenCrab evidence, standards excerpts, constraints, natural-language and doodle intents, prompt blocks, and deterministic engine contract for Codex/LLM/MCP-backed design generation. `review-panel` generates a local before/after HTML panel with original SVG, alternative SVG, intent summary, recognition/topology summaries, apply checks, and engine QA gates. `export-package` writes `projects/<project>/exports/export_manifest_###.json` and `projects/<project>/exports/<project>_export_###.zip`. The ZIP bundles the latest status, manifests, OpenCrab sync results, edit intents, handoff, workflow report, apply report, engine reports, alternative SVG, and review panel for downstream agents or SaaS upload. Source SVG inclusion is opt-in with `--include-source-svg`. `verify-package` validates an exported ZIP before handoff. It checks ZIP integrity, the embedded export manifest, required files, archive membership, file sizes, and SHA-256 hashes. Use `--check-local-files` when validating on the same machine that produced the package. `doctor` writes `projects/<project>/diagnostics/doctor_report_###.json`. It diagnoses the local framework install, OpenCrab MCP configuration, project readiness gates, latest native SVG candidate, and optional export ZIP verification in one report. Use `--strict` in CI, OAuth upload flows, or MCP handoffs. `release-audit` writes `projects/<project>/audits/release_audit_###.json`. It is the final handoff gate: it checks project candidate readiness, OpenCrab evidence, topology/standards/constraints, native SVG output, package verification, and doctor diagnostics in one report. `workflow-contract` prints the authoritative engine-stage contract for the framework. It fixes the Claude-style split into `recognition_engine`, `topology_engine`, `opencrab_engine`, `intent_engine`, `solver_engine`, `svg_mutation_engine`, and `qa_engine`, while keeping the production rule explicit: OpenCrab evidence is required, LLMs may author intent JSON but not final SVG coordinates, and final candidates must mutate existing SVG geometry in place instead of adding raster or zoning-overlay replacements. With `--state <json>`, it audits artifact/gate readiness and reports the first blocked stage. `mcp-manifest` writes or prints a machine-readable tool catalog for Codex exec, MCP wrappers, OAuth upload workers, and SaaS ingestion services. It describes each CLI tool id, subcommand, required arguments, outputs, gates, OpenCrab MCP requirement, recommended command sequences, and security boundaries. `mcp-config` writes or prints runtime configuration for MCP clients and OAuth workers, including the `crab-archi-design-mcp --stdio` command, default `CRAB_ARCHI_PROJECT_ROOT`, Codex-style `mcpServers` JSON, smoke-test messages, and worker preflight commands. `mcp-smoke` starts the configured stdio MCP server and verifies `initialize` plus `tools/list`. It writes `diagnostics/mcp_smoke_report_###.json` and can run with `--strict` in CI or before OAuth/SaaS deployment. `crab-archi-design-mcp` starts a dependency-free stdio JSON-RPC bridge. It supports MCP `initialize`, `tools/list`, and `tools/call`, then maps tool calls back to the tested CLI commands. For the full revision loop, see [docs/edit_loop.md](docs/edit_loop.md). ## Agent Runtimes (Codex, Claude Code, MCP clients) The framework is agent-runtime-neutral. [AGENTS.md](AGENTS.md) is the operating contract read by Codex CLI and other agents: hard rules, canonical commands, artifact paths, and the definition of done. [docs/codex_integration.md](docs/codex_integration.md) covers the three wiring options — exec mode via `mcp-manifest`, the stdio MCP server via `mcp-config` + `codex mcp add`, and the localhost studio HTTP API shared between human annotators and headless agents. ## Repository Scope This repository contains the reusable framework shell, schemas, and orchestration layer. It does not include proprietary SVG drawings, project outputs, or OpenCrab-saas internal artifacts. ## Core Principle ```text Original SVG -> Recognition IR v2 -> Safe SVG load / style / units / transform normalization -> Shape and path flattening -> Role classification -> Recognition Manifest -> Constraint Graph -> OpenCrab MCP Ontology Evidence -> OpenCrab Sync -> Standards Evidence -> Standards Manifest -> Design Intent JSON -> Workflow Run -> Edit Brief -> Project Status -> Design Handoff -> Native SVG Solver -> QA -> Export Package -> Doctor -> MCP/OAuth Tool Manifest -> Natural Language / Doodle Edit Loop ``` ## Status This is the first clean framework extraction. The deterministic recognition/redraw engine is expected to be connected through adapters or MCP tools.