layout-canvas 0.1.0__tar.gz

layout_canvas-0.1.0/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.venv
+venv
+__pycache__
+*.pyc
+.tmp_*
+tests/
+docs/
+klayout/
+*.gds
+*.oas
+.claude
+.codeium

layout_canvas-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src tests
+
+      - name: Validate Block IR JSON Schema
+        run: |
+          layout-canvas schema > block_ir_schema.json
+          python -c "import json, jsonschema; schema=json.load(open('block_ir_schema.json')); doc=json.load(open('examples/diffamp.json')); jsonschema.validate(doc, schema); print('Schema validation passed!')"
+
+      - name: Test Block compilation and export
+        run: |
+          layout-canvas list-blocks
+          layout-canvas compile examples/diffamp.json --out diffamp.gds
+
+      - name: Run test suite
+        run: |
+          pytest -v --tb=short

layout_canvas-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+# Release pipeline: tag v* → build → verify → PyPI (OIDC trusted
+# publishing, no stored secrets) + GitHub Release with the wheel attached.
+#
+# One-time setup (documented in docs/RELEASING.md):
+#   1. PyPI → Account → Publishing → "add a new pending publisher":
+#      owner=Kairos2425 repo=layout-canvas workflow=release.yml
+#      environment=pypi
+#   2. GitHub repo → Settings → Environments → new environment "pypi"
+#      (optional: require a reviewer before publish runs)
+#
+# Manual `workflow_dispatch` runs build+check only — the publish and
+# github-release jobs are gated on refs/tags/v*.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build + verify artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      - name: Smoke-test the wheel (fresh install + CLI entry point)
+        run: |
+          pip install dist/*.whl
+          layout-canvas schema | head -5
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/layout-canvas
+    permissions:
+      id-token: write # OIDC trusted publishing — no API token in secrets
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        # To stage on TestPyPI first, set on the step:
+        #   with:
+        #     repository-url: https://test.pypi.org/legacy/
+
+  github-release:
+    name: GitHub Release with dist artifacts
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

layout_canvas-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+.git/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.gds
+*.oas
+*.drc.txt
+*.lvs.out
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+ENV/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+uv.lock
+
+.tmp_*
+waves.dat
+# private PDK descriptors never enter git (docs/PDK_DESCRIPTORS.md)
+*.pdk.json
+
+# investor/fundraising docs stay local — never committed or pushed
+INVESTOR_*.md
+
+
+
+.wrangler/

layout_canvas-0.1.0/AGENTS.md

@@ -0,0 +1,19 @@
+# Agent entry
+
+**If you are an AI agent**, read `skills/layout-canvas/SKILL.md` first — it is
+the operating manual for driving this repository's layout compiler through MCP
+(`layout-canvas mcp`), including the 8-step design loop, the typed edit ops,
+and how to read fail-closed results.
+
+Working in this repository as a contributor:
+
+- Follow `CONTRIBUTING.md`; commits use `feat:` / `fix:` / `docs:` / `test:` /
+  `chore:` prefixes.
+- Verification is fail-closed by contract (ADR 0002, 0005): never make a DRC,
+  LVS or simulation path report a pass when a tool, model or signal is
+  missing, and never loosen a rule value to make a check green.
+- Machine-specific paths go through environment variables
+  (`docs/EXTERNAL_TOOLS.md`); private PDKs and run products never enter git.
+- Run `.venv\Scripts\python.exe -m pytest tests -q` before committing; set
+  `LAYOUT_CANVAS_NGSPICE` to a console ngspice to exercise the simulation
+  tests instead of skipping them.

layout_canvas-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Layout Canvas
+
+## Development Setup
+
+```bash
+git clone https://github.com/Kairos2425/layout-canvas.git
+cd layout-canvas
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+ruff check src tests
+```
+
+## Adding a New Block
+
+1. Create `src/layout_canvas/blocks/{pdk}/{block_name}.py`
+2. Define `BlockSpec` with params, ports, constraints
+3. Implement build function (returns `gf.Component`)
+4. Optionally implement netlist emitter
+5. Register with `@register(spec, netlist=...)`
+6. Import in `src/layout_canvas/blocks/{pdk}/__init__.py`
+
+Example:
+
+```python
+from layout_canvas.blocks.base import register
+from layout_canvas.ir.model import BlockSpec, ParamSpec, PortSpec
+
+spec = BlockSpec(
+    name="sky130.my_block",
+    pdk="sky130",
+    level="L1",
+    summary="My parametric block",
+    params=[
+        ParamSpec(name="width", type="float", default=1.0, unit="um", min=0.5, max=10.0),
+    ],
+    ports=[
+        PortSpec(name="in", layer="met1", direction="input"),
+    ],
+)
+
+@register(spec)
+def _build(width: float) -> gf.Component:
+    c = gf.Component()
+    # ... add geometry
+    return c
+```
+
+## Code Style
+
+- Line length: 100
+- Imports: sorted with `ruff`
+- Type hints: required for public APIs
+- Docstrings: Google style for public functions
+
+## License
+
+All contributions are licensed under MIT — see `LICENSE`. Bundled Sky130 model
+files under `examples/models/sky130/` remain Apache-2.0 (upstream SkyWater),
+and `NOTICE` reserves the "Layout Canvas" name.
+
+By contributing you certify the [Developer Certificate of Origin](https://developercertificate.org/)
+(DCO 1.1): you wrote the change or have the right to submit it under MIT, and
+you understand it becomes part of the open core. If you can, add
+`Signed-off-by: Name <email>` to the commit; either way, opening a PR
+constitutes the certification.

layout_canvas-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 layout-canvas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

layout_canvas-0.1.0/NOTICE

@@ -0,0 +1,23 @@
+layout-canvas
+Copyright (c) 2026 layout-canvas contributors
+
+This product includes software developed by the layout-canvas project.
+
+Third-party attribution
+-----------------------
+Files under `examples/models/sky130/` are verbatim from
+google/skywater-pdk-libs-sky130_fd_pr and remain licensed under the
+Apache License, Version 2.0 (copyright SkyWater / Google contributors).
+
+Trademark
+---------
+"Layout Canvas" and the layout-canvas name are trademarks of the project
+authors. The MIT license covers the software only — it does not grant
+permission to use the project name or marks for derivative products or
+services. Forks should be renamed.
+
+Commercial use
+--------------
+The core is MIT-licensed and free for commercial use. The authors also
+offer commercial arrangements (private PDK enablement, enterprise support,
+hosted gallery/registry services) — see `docs/COMMERCIAL.md`.

layout_canvas-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: layout-canvas
+Version: 0.1.0
+Summary: Block-level, AI-native analog layout canvas: Block IR + parametric blocks + DRC/LVS/PEX verification + Virtuoso export.
+Project-URL: Repository, https://github.com/Kairos2425/layout-canvas
+Project-URL: Issues, https://github.com/Kairos2425/layout-canvas/issues
+Project-URL: Documentation, https://github.com/Kairos2425/layout-canvas/tree/main/docs
+Project-URL: Gallery, https://github.com/Kairos2425/layout-canvas-gallery
+Author: layout-canvas contributors
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: analog,drc,eda,gds,layout,llm-agent,lvs,mcp,pdk,spectre,virtuoso
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Requires-Dist: gdsfactory>=8.0
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: jsonschema>=4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Layout Canvas
+
+**Block-level, AI-native analog layout canvas** — parametric block library, typed
+Block IR, deterministic layout compiler, in-process DRC/LVS/PEX verification, and
+a local-first web canvas that AI agents can drive through MCP.
+
+**Live demo → https://kairos2425.github.io/layout-canvas/**
+
+```
+Block IR (JSON) ── compile ──▶ gdsfactory ──▶ GDS
+      │                            │
+      │                            └──▶ SPICE netlist ──▶ LVS vs extracted netlist
+      │                            └──▶ KLayout pya ──▶ DRC subset + extraction
+      │                            └──▶ ngspice ──▶ schematic & post-layout sim
+      │
+      └── constraints · ports · metadata ──▶ MCP tools for AI agents
+```
+
+## What it does
+
+| Stage | Capability |
+|---|---|
+| **IR** | Pydantic-typed Block IR: instances, params, placements, nets, ports |
+| **Blocks** | Sky130: diff_pair · current_mirror · ota_5t · strongarm · cap_array · guard_ring — IHP SG13G2: diff_pair · current_mirror · ota_5t · guard_ring |
+| **Compile** | Design → hierarchical GDS + SPICE; top-level router with keep-outs, risers, via stacks |
+| **DRC** | In-process KLayout engine: real width / spacing / via-enclosure subset with violation bboxes drawn back on the canvas (RVE-style) |
+| **LVS** | `LayoutToNetlist` extraction + `NetlistComparer` topology match; passive blocks get connectivity-semantics comparison; mismatched nets are localized and highlighted |
+| **PEX sim** | Extracted netlist → BSIM4/PSP foundry models via ngspice; internal-node probes (`xd1.tail`), custom testbenches |
+| **External PDKs** | `*.pdk.json` descriptors via `LAYOUT_CANVAS_PDK_DIR`/`LAYOUT_CANVAS_PDKS` — layer map + extract recipe + DRC subset + model prelude + generic `gen_diff_pair`/`gen_current_mirror`/`gen_guard_ring` generators, no code (`docs/PDK_DESCRIPTORS.md`) |
+| **Testbenches** | Named sim setups on the IR (schematic/extracted, op/tran/ac/dc, probes) + per-spec pass/fail/unavailable with reasons — `final/min/max/mean/pp/db/bw_3db` plus transient `settling`/`slew`/`overshoot` (with `tol`); CLI exit codes, session run history |
+| **Export** | Virtuoso SKILL (shapes/instances, tech-lib attach, mirror/mag transforms) + Spectre netlist, GDS/OASIS, SPICE — plus `virtuoso-accept`: static SKILL/.scs checks anywhere, real Virtuoso/spectre acceptance over SSH on an EDA host (`docs/VIRTUOSO_ACCEPTANCE.md`; 30-min bring-up: `docs/CADENCE_INTEGRATION.md`) |
+| **Import** | `import-netlist`: upstream SPICE/Spectre subckt netlists → Block IR draft (blocks matched by name + port signature; unmapped instances named, never guessed) — the upstream-pipeline on-ramp |
+| **Interfaces** | CLI · local web canvas · MCP stdio server (35 tools) |
+
+## Install
+
+```bash
+pip install layout-canvas  # PyPI — or: pip install git+https://github.com/Kairos2425/layout-canvas
+pip install klayout        # in-process DRC/LVS/extraction engine
+pytest                     # 245 tests; tool-dependent tests auto-skip
+```
+
+Optional tools (probed adapters — absent tools report `unavailable`, never fake results):
+
+- **ngspice** — schematic & post-layout simulation (`LAYOUT_CANVAS_NGSPICE=<path>`)
+- **KLayout app / netgen / magic** — full foundry decks (`LAYOUT_CANVAS_KLAYOUT`, …)
+- **IHP SG13G2 models** — `LAYOUT_CANVAS_IHP_MODELS`, `LAYOUT_CANVAS_OSDI_DIR`
+  (see `docs/EXTERNAL_TOOLS.md`)
+- **Remote Virtuoso/spectre host** — `LAYOUT_CANVAS_VIRTUOSO_HOST`,
+  `LAYOUT_CANVAS_VIRTUOSO_DIR`, `LAYOUT_CANVAS_SPECTRE_MODELS`
+  (SSH key auth; see `docs/VIRTUOSO_ACCEPTANCE.md`)
+
+## Quick start
+
+### CLI
+
+```bash
+layout-canvas compile examples/diffamp.json -o diffamp.gds    # IR → GDS
+layout-canvas netlist examples/diffamp.json -o diffamp.sp    # IR → SPICE
+layout-canvas schema                                         # Block IR JSON schema
+layout-canvas web --port 8080                                # local canvas UI
+layout-canvas mcp                                            # MCP stdio server
+```
+
+### Web canvas
+
+`layout-canvas web` opens the editor at `http://127.0.0.1:8080`: place blocks,
+edit params, wire nets, then **Verify** (extract → DRC → LVS, violations painted
+on the layout) and **PEX** (post-layout ngspice on extracted netlist with
+waveform sparklines). Projects save/load as JSON — local-first, nothing leaves
+the machine.
+
+### Python API
+
+```python
+from layout_canvas.ir.model import Design
+from layout_canvas.tools.verify import verify_design
+import layout_canvas.blocks  # registers all block generators
+
+d = Design.model_validate({
+    "name": "diffamp", "pdk": "sky130",
+    "instances": [{"id": "U1", "block": "sky130.diff_pair",
+                   "params": {"fingers": 4, "width": 2.0},
+                   "placement": {"x": 0, "y": 0}}],
+    "nets": [], "ports": [{"name": "inp", "pin": "U1.inp"}],
+})
+r = verify_design(d)          # extract → DRC → LVS in one call
+r["passed"], r["drc"]["total_violations"], r["lvs"]["match"]
+```
+
+Post-layout simulation on the extracted netlist:
+
+```python
+from layout_canvas.tools.sim import simulate_extracted
+res = simulate_extracted(d, probes=["out", "tail"], vdd=1.8)
+# res["status"], res["waves"]  →  per-probe waveform vectors
+```
+
+### MCP (AI agents)
+
+Point any MCP client at `layout-canvas mcp` (stdio). Agents get the full loop:
+`open_design` → `insert_block_into_layout` / `transact` → `verify_design` →
+`run_simulation(source="extracted", probes=[...])` → `export_virtuoso` /
+`save_project`. `probe_environment` reports which EDA tools are live.
+
+## Repository layout
+
+```
+src/layout_canvas/
+  ir/          Block IR schema (Pydantic)
+  blocks/      parametric generators (sky130/, ihp_sg13g2/)
+  compiler/    GDS/SPICE/Skill compile, router, Virtuoso export, PPA
+  engine/      transactional edit session (snapshot/undo)
+  tools/       drc, extract, lvs, sim, verify, backends
+  web/         local canvas app + gallery
+  mcp/         stdio MCP server
+tests/         245 tests incl. real-ngspice / real-PDK smokes
+docs/          architecture, ADRs 0001-0009, external-tool setup
+deploy/        Dockerfile + compose for the web app
+```
+
+## Security & privacy
+
+- **Local-first by design.** The web app binds `127.0.0.1`; project files,
+  GDS output and simulation decks stay on your machine. No telemetry, no
+  cloud calls, no analytics.
+- **No secrets in-repo.** PDK model paths, tool binaries and simulator paths
+  are supplied via `LAYOUT_CANVAS_*` environment variables — see
+  `docs/EXTERNAL_TOOLS.md`. Proprietary PDKs are never shipped or required.
+- **Fail-closed verification.** DRC/LVS/sim report real tool results;
+  missing tools return `unavailable`/`refused`, never fabricated green.
+- **Process isolation.** GPL tools (KLayout app, netgen) run as external
+  processes or the pip `klayout` module — no GPL code is linked in.
+- Report vulnerabilities by opening a GitHub issue marked `security`, or
+  contact the maintainer directly. Please do not include proprietary PDK
+  material or NDA'd data in public reports.
+
+## License
+
+MIT — see `LICENSE`. The "Layout Canvas" name is reserved (see `NOTICE`);
+bundled Sky130 model files under `examples/models/sky130/` are upstream
+SkyWater files and remain Apache-2.0. Commercial arrangements (private PDK
+enablement, enterprise deployment, support): `docs/COMMERCIAL.md`.
+
+## Prior art & references
+
+Independently implemented; product-direction inspiration from Analog Canvas
+(github.com/cascode-ai/analog-canvas). Built on
+[gdsfactory](https://github.com/gdsfactory/gdsfactory),
+[KLayout](https://www.klayout.de/), ngspice, and the Sky130 / IHP SG13G2
+open PDKs. Related: Glayout (OpenFASOC), ALIGN, Layout21, BAG, VLSIR.

layout_canvas-0.1.0/README.md

@@ -0,0 +1,151 @@
+# Layout Canvas
+
+**Block-level, AI-native analog layout canvas** — parametric block library, typed
+Block IR, deterministic layout compiler, in-process DRC/LVS/PEX verification, and
+a local-first web canvas that AI agents can drive through MCP.
+
+**Live demo → https://kairos2425.github.io/layout-canvas/**
+
+```
+Block IR (JSON) ── compile ──▶ gdsfactory ──▶ GDS
+      │                            │
+      │                            └──▶ SPICE netlist ──▶ LVS vs extracted netlist
+      │                            └──▶ KLayout pya ──▶ DRC subset + extraction
+      │                            └──▶ ngspice ──▶ schematic & post-layout sim
+      │
+      └── constraints · ports · metadata ──▶ MCP tools for AI agents
+```
+
+## What it does
+
+| Stage | Capability |
+|---|---|
+| **IR** | Pydantic-typed Block IR: instances, params, placements, nets, ports |
+| **Blocks** | Sky130: diff_pair · current_mirror · ota_5t · strongarm · cap_array · guard_ring — IHP SG13G2: diff_pair · current_mirror · ota_5t · guard_ring |
+| **Compile** | Design → hierarchical GDS + SPICE; top-level router with keep-outs, risers, via stacks |
+| **DRC** | In-process KLayout engine: real width / spacing / via-enclosure subset with violation bboxes drawn back on the canvas (RVE-style) |
+| **LVS** | `LayoutToNetlist` extraction + `NetlistComparer` topology match; passive blocks get connectivity-semantics comparison; mismatched nets are localized and highlighted |
+| **PEX sim** | Extracted netlist → BSIM4/PSP foundry models via ngspice; internal-node probes (`xd1.tail`), custom testbenches |
+| **External PDKs** | `*.pdk.json` descriptors via `LAYOUT_CANVAS_PDK_DIR`/`LAYOUT_CANVAS_PDKS` — layer map + extract recipe + DRC subset + model prelude + generic `gen_diff_pair`/`gen_current_mirror`/`gen_guard_ring` generators, no code (`docs/PDK_DESCRIPTORS.md`) |
+| **Testbenches** | Named sim setups on the IR (schematic/extracted, op/tran/ac/dc, probes) + per-spec pass/fail/unavailable with reasons — `final/min/max/mean/pp/db/bw_3db` plus transient `settling`/`slew`/`overshoot` (with `tol`); CLI exit codes, session run history |
+| **Export** | Virtuoso SKILL (shapes/instances, tech-lib attach, mirror/mag transforms) + Spectre netlist, GDS/OASIS, SPICE — plus `virtuoso-accept`: static SKILL/.scs checks anywhere, real Virtuoso/spectre acceptance over SSH on an EDA host (`docs/VIRTUOSO_ACCEPTANCE.md`; 30-min bring-up: `docs/CADENCE_INTEGRATION.md`) |
+| **Import** | `import-netlist`: upstream SPICE/Spectre subckt netlists → Block IR draft (blocks matched by name + port signature; unmapped instances named, never guessed) — the upstream-pipeline on-ramp |
+| **Interfaces** | CLI · local web canvas · MCP stdio server (35 tools) |
+
+## Install
+
+```bash
+pip install layout-canvas  # PyPI — or: pip install git+https://github.com/Kairos2425/layout-canvas
+pip install klayout        # in-process DRC/LVS/extraction engine
+pytest                     # 245 tests; tool-dependent tests auto-skip
+```
+
+Optional tools (probed adapters — absent tools report `unavailable`, never fake results):
+
+- **ngspice** — schematic & post-layout simulation (`LAYOUT_CANVAS_NGSPICE=<path>`)
+- **KLayout app / netgen / magic** — full foundry decks (`LAYOUT_CANVAS_KLAYOUT`, …)
+- **IHP SG13G2 models** — `LAYOUT_CANVAS_IHP_MODELS`, `LAYOUT_CANVAS_OSDI_DIR`
+  (see `docs/EXTERNAL_TOOLS.md`)
+- **Remote Virtuoso/spectre host** — `LAYOUT_CANVAS_VIRTUOSO_HOST`,
+  `LAYOUT_CANVAS_VIRTUOSO_DIR`, `LAYOUT_CANVAS_SPECTRE_MODELS`
+  (SSH key auth; see `docs/VIRTUOSO_ACCEPTANCE.md`)
+
+## Quick start
+
+### CLI
+
+```bash
+layout-canvas compile examples/diffamp.json -o diffamp.gds    # IR → GDS
+layout-canvas netlist examples/diffamp.json -o diffamp.sp    # IR → SPICE
+layout-canvas schema                                         # Block IR JSON schema
+layout-canvas web --port 8080                                # local canvas UI
+layout-canvas mcp                                            # MCP stdio server
+```
+
+### Web canvas
+
+`layout-canvas web` opens the editor at `http://127.0.0.1:8080`: place blocks,
+edit params, wire nets, then **Verify** (extract → DRC → LVS, violations painted
+on the layout) and **PEX** (post-layout ngspice on extracted netlist with
+waveform sparklines). Projects save/load as JSON — local-first, nothing leaves
+the machine.
+
+### Python API
+
+```python
+from layout_canvas.ir.model import Design
+from layout_canvas.tools.verify import verify_design
+import layout_canvas.blocks  # registers all block generators
+
+d = Design.model_validate({
+    "name": "diffamp", "pdk": "sky130",
+    "instances": [{"id": "U1", "block": "sky130.diff_pair",
+                   "params": {"fingers": 4, "width": 2.0},
+                   "placement": {"x": 0, "y": 0}}],
+    "nets": [], "ports": [{"name": "inp", "pin": "U1.inp"}],
+})
+r = verify_design(d)          # extract → DRC → LVS in one call
+r["passed"], r["drc"]["total_violations"], r["lvs"]["match"]
+```
+
+Post-layout simulation on the extracted netlist:
+
+```python
+from layout_canvas.tools.sim import simulate_extracted
+res = simulate_extracted(d, probes=["out", "tail"], vdd=1.8)
+# res["status"], res["waves"]  →  per-probe waveform vectors
+```
+
+### MCP (AI agents)
+
+Point any MCP client at `layout-canvas mcp` (stdio). Agents get the full loop:
+`open_design` → `insert_block_into_layout` / `transact` → `verify_design` →
+`run_simulation(source="extracted", probes=[...])` → `export_virtuoso` /
+`save_project`. `probe_environment` reports which EDA tools are live.
+
+## Repository layout
+
+```
+src/layout_canvas/
+  ir/          Block IR schema (Pydantic)
+  blocks/      parametric generators (sky130/, ihp_sg13g2/)
+  compiler/    GDS/SPICE/Skill compile, router, Virtuoso export, PPA
+  engine/      transactional edit session (snapshot/undo)
+  tools/       drc, extract, lvs, sim, verify, backends
+  web/         local canvas app + gallery
+  mcp/         stdio MCP server
+tests/         245 tests incl. real-ngspice / real-PDK smokes
+docs/          architecture, ADRs 0001-0009, external-tool setup
+deploy/        Dockerfile + compose for the web app
+```
+
+## Security & privacy
+
+- **Local-first by design.** The web app binds `127.0.0.1`; project files,
+  GDS output and simulation decks stay on your machine. No telemetry, no
+  cloud calls, no analytics.
+- **No secrets in-repo.** PDK model paths, tool binaries and simulator paths
+  are supplied via `LAYOUT_CANVAS_*` environment variables — see
+  `docs/EXTERNAL_TOOLS.md`. Proprietary PDKs are never shipped or required.
+- **Fail-closed verification.** DRC/LVS/sim report real tool results;
+  missing tools return `unavailable`/`refused`, never fabricated green.
+- **Process isolation.** GPL tools (KLayout app, netgen) run as external
+  processes or the pip `klayout` module — no GPL code is linked in.
+- Report vulnerabilities by opening a GitHub issue marked `security`, or
+  contact the maintainer directly. Please do not include proprietary PDK
+  material or NDA'd data in public reports.
+
+## License
+
+MIT — see `LICENSE`. The "Layout Canvas" name is reserved (see `NOTICE`);
+bundled Sky130 model files under `examples/models/sky130/` are upstream
+SkyWater files and remain Apache-2.0. Commercial arrangements (private PDK
+enablement, enterprise deployment, support): `docs/COMMERCIAL.md`.
+
+## Prior art & references
+
+Independently implemented; product-direction inspiration from Analog Canvas
+(github.com/cascode-ai/analog-canvas). Built on
+[gdsfactory](https://github.com/gdsfactory/gdsfactory),
+[KLayout](https://www.klayout.de/), ngspice, and the Sky130 / IHP SG13G2
+open PDKs. Related: Glayout (OpenFASOC), ALIGN, Layout21, BAG, VLSIR.