FABulous-FPGA 2__tar.gz

fabulous_fpga-2/.cursorrules

@@ -0,0 +1,56 @@
+# AGENTS.md
+
+## Project Overview
+
+FABulous is a parametric FPGA fabric generator. It takes a fabric definition (CSV or YAML), builds an in-memory fabric model, and emits the HDL, nextpnr chip database, synthesis scripts, geometry, and bitstream needed to target that fabric.
+
+```text
+config (CSV/YAML) → fabric model → HDL + chip DB + synth scripts
+user design → Yosys (synth) → nextpnr (P&R) → FASM → bitstream
+```
+
+## How to Work in This Repo
+
+- **Python deps: `uv`.** Run `uv sync` after pulling; add deps with `uv add` (`--group dev` for dev-only). Never hand-edit `uv.lock`. Run commands as `uv run <cmd>` or activate `.venv/`.
+- **EDA toolchain: Nix.** `flake.nix` pins Yosys, nextpnr, OpenROAD, GHDL, Librelane, etc. The **GDS / ASIC flow** (anything under `gds_flow_test`, `librelane_plugin_fabulous`, or `fabulous/fabric_generator/gds_generator`) requires the Nix shell — `nix develop` first, when inside the shell you will not need `uv`. Don't try to substitute system installs of these tools; CI uses Nix and version drift will burn you.
+- **Tasks**: `Taskfile.yml` is the canonical runner. The ones you'll use most: `task test` (forwards args after `--`; pass `--runslow` for slow tests), `task ci` (run before pushing), `task smoke-test` (end-to-end). `task --list` for the rest.
+- **Pre-commit is enforced** (ruff, docstring linting, dependency hygiene, etc.). If a hook fails, fix the cause — don't `--no-verify`.
+
+## Coding Taste
+
+Rules that make changes feel native. Follow them even when a tool's defaults disagree.
+
+### Style
+
+- **Python 3.12+**. Built-in generics only (`list[int]`, `X | None`); never `typing.List`/`Optional`.
+- **Paths**: `pathlib.Path`. Never `os.path` or string concatenation.
+- **Logging**: `loguru` (`from loguru import logger`). Not `print`, not stdlib `logging`.
+- **Docstrings**: NumPy style — `pydoclint` + `interrogate` (≥95% coverage) enforce this.
+- **Inline code in docstrings/comments**: We use MyST for documentation. We use single "`" for raw text and "_" for italic.
+- **Naming**: this repo right now uses `camelCase` for variables/functions, `PascalCase` for classes, `CONSTANT_CASE` for module constants. Use snake case for all newly created methods and variables as we slow transition to meet PEP 8.  
+- Formatting (line length, quotes, etc.) is whatever `ruff format` produces.
+
+### Design
+
+- **No fallbacks, no silent retries.** Surface failures with clear errors. A stack trace beats a wrong result.
+- **Fix root causes.** If a fix doesn't change behavior the way you expected, stop and re-analyze before patching again.
+- **Validate at boundaries, trust internals.** Defensive checks belong where untrusted input enters (parsers, CLI, external tools).
+- **No premature abstraction.** Three similar lines beat a speculative helper. Ship the smallest correct change.
+- **Clear over clever.** Loops over unreadable comprehensions; parsers over paragraph-long regexes.
+- **Comments explain *why*, not *what*.** Reserve them for hidden constraints, non-obvious invariants, bug-specific workarounds. Don't reference task numbers or callers — that rots.
+- **Pydantic** for runtime-validated config (`fabulous_settings.py`); **dataclasses** for the fabric model — keep them light, no heavy logic.
+
+### Testing
+
+- `pytest` + `pytest-mock` (use the `mocker` fixture; don't import `unittest.mock`).
+- Mark slow tests `@pytest.mark.slow` so default `task test` stays fast.
+- Prefer real in-memory fabric fixtures over heavy mocks.
+- `cocotb` is available for RTL-level verification, not for Python logic.
+- Try to reuse fixture as much as possible.
+- Try to parameterize the test if possible
+
+## House Rules
+
+- Don't edit the symlinked agent files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`) — edit `AGENTS.md`.
+- Don't add new top-level packages without a clear home in the layout above.
+- When in doubt, read `Taskfile.yml`, `pyproject.toml`, and `tests/conftest.py` — they encode the live conventions. The Sphinx docs under `docs/` cover user-facing flow.

fabulous_fpga-2/.devcontainer/Dockerfile

@@ -0,0 +1,76 @@
+FROM ubuntu:24.04
+
+# Install minimal dependencies and set up non-root user (UID 1000)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates xz-utils git sudo && \
+    rm -rf /var/lib/apt/lists/* && \
+    userdel -r ubuntu 2>/dev/null || true && \
+    useradd -m -s /bin/bash -u 1000 nixuser && \
+    echo 'nixuser ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/nixuser && \
+    chmod 0440 /etc/sudoers.d/nixuser && \
+    mkdir -p /nix && chown -R nixuser:nixuser /nix
+
+# Install Nix as nixuser and configure for single-user mode with flakes
+RUN su - nixuser -c 'curl -L https://nixos.org/nix/install | sh -s -- --no-daemon' && \
+    mkdir -p /home/nixuser/.config/nix && \
+    { echo 'experimental-features = nix-command flakes'; \
+    echo 'cores = 0'; \
+    echo 'extra-substituters = https://nix-cache.fossi-foundation.org'; \
+    echo 'extra-trusted-public-keys = nix-cache.fossi-foundation.org:3+K59iFwXqKsL7BNu6Guy0v+uTlwsxYQxjspXzqLYQs='; \
+    echo 'build-users-group ='; \
+    } > /home/nixuser/.config/nix/nix.conf && \
+    chown -R nixuser:nixuser /home/nixuser/.config
+
+# Copy project files for Nix build
+WORKDIR /build
+COPY --chown=nixuser:nixuser flake.nix flake.lock ./
+COPY --chown=nixuser:nixuser nix/ ./nix/
+COPY --chown=nixuser:nixuser pyproject.toml uv.lock build_hooks.py ./
+COPY --chown=nixuser:nixuser fabulous/ ./fabulous/
+
+# Build dev shell profile as nixuser and clean up to reduce image size
+USER nixuser
+ENV PATH="/home/nixuser/.nix-profile/bin:$PATH"
+RUN nix develop --profile /nix/var/nix/profiles/devshell --command true && \
+    nix store gc && \
+    nix store optimise
+
+# Switch back to root for system-level setup
+USER root
+
+# Set up workspace and runtime dir
+RUN mkdir -p /workspaces /run/user/1000 && \
+    chown nixuser:nixuser /workspaces /run/user/1000 && \
+    chmod 700 /run/user/1000
+
+# Install devshell profile script, resolving DEVSHELL_DIR at build time.
+# Sourced via BASH_ENV (non-interactive), /etc/bash.bashrc (system interactive),
+# and ~/.bashrc (user interactive) to cover all shell invocation modes.
+COPY .devcontainer/devshell.sh.tpl /tmp/devshell.sh.tpl
+RUN DEVSHELL_DIR=$(find /nix/store -maxdepth 1 -type d -name "*-devshell-dir" | head -1) && \
+    sed "s|@@DEVSHELL_DIR@@|$DEVSHELL_DIR|" /tmp/devshell.sh.tpl > /etc/profile.d/devshell.sh && \
+    rm /tmp/devshell.sh.tpl && \
+    chmod +x /etc/profile.d/devshell.sh && \
+    echo 'source /etc/profile.d/devshell.sh' >> /home/nixuser/.bashrc && \
+    echo 'source /etc/profile.d/devshell.sh' >> /etc/bash.bashrc && \
+    chown nixuser:nixuser /home/nixuser/.bashrc
+
+# Fix GPG "invalid signature" errors when devcontainer features run apt-get update
+# in Codespaces overlay builds. The base image enables gzip indexes (docker-gzip-indexes)
+# which causes file size mismatches across overlay2 layers during GPG verification.
+RUN rm -f /etc/apt/apt.conf.d/docker-gzip-indexes && \
+    rm -rf /var/lib/apt/lists/* && \
+    apt-get update
+
+# Run as nixuser by default and set environment variables
+USER nixuser
+ENV BASH_ENV=/etc/profile.d/devshell.sh \
+    XDG_RUNTIME_DIR=/run/user/1000 \
+    QT_X11_NO_MITSHM=1 \
+    QT_QPA_PLATFORM=offscreen \
+    REPO_ROOT=/workspaces \
+    PRJ_ROOT=/workspaces \
+    PATH="/nix/var/nix/profiles/devshell/bin:/home/nixuser/.nix-profile/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+WORKDIR /workspaces
+CMD ["/bin/bash"]

fabulous_fpga-2/.devcontainer/codespace/devcontainer.json

@@ -0,0 +1,57 @@
+{
+    "name": "Remote (codespace)",
+    "image": "ghcr.io/fpga-research/fabulous:latest",
+    "features": {
+        "ghcr.io/devcontainers/features/desktop-lite:1": {
+            "password": "fabulous",
+            "webPort": "6080",
+            "vncPort": "5901"
+        }
+    },
+    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+    "containerEnv": {
+        "QT_QPA_PLATFORM": "xcb"
+    },
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "python.defaultInterpreterPath": "python",
+                "python.analysis.typeCheckingMode": "basic",
+                "editor.formatOnSave": true,
+                "[python]": {
+                    "editor.defaultFormatter": "charliermarsh.ruff",
+                    "editor.codeActionsOnSave": {
+                        "source.fixAll.ruff": "explicit",
+                        "source.organizeImports.ruff": "explicit"
+                    }
+                },
+                "terminal.integrated.cwd": "/workspaces/${localWorkspaceFolderBasename}",
+                "dotfiles.repository": "",
+                "dotfiles.installCommand": ""
+            },
+            "extensions": [
+                "charliermarsh.ruff",
+                "ms-python.python"
+            ]
+        },
+        "codespaces": {
+            "portsAttributes": {
+                "6080": {
+                    "label": "Desktop (noVNC)",
+                    "onAutoForward": "ignore",
+                    "visibility": "private"
+                },
+                "5901": {
+                    "label": "VNC",
+                    "onAutoForward": "ignore",
+                    "visibility": "private"
+                }
+            }
+        }
+    },
+    "postAttachCommand": "bash .devcontainer/display-switch.sh",
+    "remoteUser": "nixuser",
+    "hostRequirements": {
+        "cpus": 4
+    }
+}

fabulous_fpga-2/.devcontainer/devshell.sh.tpl

@@ -0,0 +1,8 @@
+# Sourced by BASH_ENV, /etc/bash.bashrc, and ~/.bashrc
+# _DEVSHELL_SOURCED guard prevents re-sourcing in nested shells
+[ -n "$_DEVSHELL_SOURCED" ] && return
+export _DEVSHELL_SOURCED=1
+
+export DEVSHELL_DIR="@@DEVSHELL_DIR@@"
+[ -f "$DEVSHELL_DIR/env.bash" ] && source "$DEVSHELL_DIR/env.bash"
+export PATH="/nix/var/nix/profiles/devshell/bin:/home/nixuser/.nix-profile/bin:$PATH"

fabulous_fpga-2/.devcontainer/display-switch.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# Configures the display server based on the environment:
+# - Codespaces: uses the built-in VNC server on :1
+# - Local Linux: switches from VNC to host X11 via socket mount
+
+if [ "$CODESPACES" = "true" ]; then
+    echo "Running in Codespaces (VNC on :1)"
+    export DISPLAY=:1
+else
+    echo "Running on Local Linux (X11 socket mount)"
+
+    # Kill internal VNC to avoid conflicts with host X11
+    pkill Xvfb 2>/dev/null || true
+    rm -f /tmp/.X11-unix/X1 2>/dev/null || true
+
+    # Link host X11 socket from mount point
+    if [ -d "/tmp/.host-X11-unix" ]; then
+        ln -sf /tmp/.host-X11-unix/* /tmp/.X11-unix/ 2>/dev/null || true
+    fi
+
+    # Use the DISPLAY variable passed from the host
+    export DISPLAY="${DISPLAY:-:0}"
+    echo "Using display: $DISPLAY"
+
+    # Disable auth (relies on xhost +local:docker on host)
+    export XAUTHORITY=""
+fi
+
+# Persist display settings to bashrc for new terminal sessions
+sed -i '/export DISPLAY=/d; /export XAUTHORITY=/d' ~/.bashrc
+echo "export DISPLAY=$DISPLAY" >> ~/.bashrc
+if [ "$CODESPACES" != "true" ]; then
+    echo 'export XAUTHORITY=""' >> ~/.bashrc
+fi

fabulous_fpga-2/.devcontainer/local/devcontainer.json

@@ -0,0 +1,47 @@
+{
+    "name": "Local",
+    "image": "ghcr.io/fpga-research/fabulous:latest",
+    "features": {
+        "ghcr.io/devcontainers/features/desktop-lite:1": {
+            "password": "fabulous",
+            "webPort": "6080",
+            "vncPort": "5901"
+        }
+    },
+    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+    // --- LOCAL LINUX SPECIFIC SETTINGS ---
+    // --net=host is required for X11: modern Linux uses abstract Unix sockets
+    // for X11, which live in the network namespace (not the filesystem).
+    // --security-opt needed for SELinux (Fedora/RHEL).
+    "runArgs": [
+        "--net=host",
+        "--security-opt=label=disable"
+    ],
+    "mounts": [
+        "source=/tmp/.X11-unix,target=/tmp/.host-X11-unix,type=bind"
+    ],
+    "containerEnv": {
+        "QT_QPA_PLATFORM": "xcb",
+        "DISPLAY": "${localEnv:DISPLAY}"
+    },
+    "postAttachCommand": "bash .devcontainer/display-switch.sh",
+    "initializeCommand": "xhost +local:docker 2>/dev/null || true",
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "python.defaultInterpreterPath": "python",
+                "python.analysis.typeCheckingMode": "basic",
+                "editor.formatOnSave": true,
+                "[python]": {
+                    "editor.defaultFormatter": "charliermarsh.ruff",
+                    "editor.codeActionsOnSave": {
+                        "source.fixAll.ruff": "explicit",
+                        "source.organizeImports.ruff": "explicit"
+                    }
+                },
+                "terminal.integrated.cwd": "/workspaces/${localWorkspaceFolderBasename}"
+            }
+        }
+    },
+    "remoteUser": "nixuser"
+}

fabulous_fpga-2/.gitattributes

@@ -0,0 +1,2 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto

fabulous_fpga-2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Execute command '....'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Example**
+Provide a minimal reproducible example.
+You may also provide your FABulous project.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Your Setup (please complete the following information):**
+ - OS: [e.g. Debian Linux]
+ - OS / kernel version: [e.g. 6.12.4-arch1-1]
+ - Python version: [e.g. 3.12.07]
+ - Yosys version: [e.g. 0.43]
+ - FABulous version / git commit id / git branch
+
+**Additional context**
+Add any other context about the problem here.

fabulous_fpga-2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+If you have questions about the usage of FABulous, please check the [FABulous discussions page](https://github.com/FPGA-Research/FABulous/discussions) .
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

fabulous_fpga-2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- Briefly describe what this PR changes and why. -->
+
+## Related Issues
+
+<!-- Link any related issues, e.g. "Closes #123". -->
+
+## Testing
+
+<!-- Describe how you tested this change. Include commands run and any relevant output. -->
+
+## Checklist
+
+- [ ] I have read [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+- [ ] I agree that my contribution is licensed under the project's [Apache License 2.0](../LICENSE).
+- [ ] I have run `pre-commit run --all-files` and `pytest` locally.
+- [ ] I have updated documentation where relevant.

fabulous_fpga-2/.github/actions/create_failure_issue/action.yaml

@@ -0,0 +1,54 @@
+name: Create failure issue
+description: Create a GitHub issue on CI failure with deduplication
+
+inputs:
+  title:
+    description: "Issue title (used for deduplication)"
+    required: true
+  body:
+    description: "Issue body in markdown"
+    required: true
+  labels:
+    description: "Comma-separated labels (first label used for dedup search)"
+    required: true
+  github_token:
+    description: "GitHub token for API access"
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Create issue on failure
+      uses: actions/github-script@v9
+      env:
+        ISSUE_TITLE: ${{ inputs.title }}
+        ISSUE_BODY: ${{ inputs.body }}
+        ISSUE_LABELS: ${{ inputs.labels }}
+      with:
+        github-token: ${{ inputs.github_token }}
+        script: |
+          const title = process.env.ISSUE_TITLE;
+          const body = process.env.ISSUE_BODY;
+          const labels = process.env.ISSUE_LABELS.split(',').map(l => l.trim());
+          const searchLabel = labels[0];
+
+          const issues = await github.rest.issues.listForRepo({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            state: 'open',
+            labels: [searchLabel],
+            per_page: 100
+          });
+
+          if (!issues.data.find(i => i.title === title)) {
+            const created = await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: title,
+              body: body,
+              labels: labels
+            });
+            console.log(`Created issue #${created.data.number}: ${title}`);
+          } else {
+            console.log('Issue already exists, skipping creation');
+          }

fabulous_fpga-2/.github/actions/prepare_FABulous_container/action.yaml

@@ -0,0 +1,126 @@
+name: Prepare FABulous workflow
+description: Composite action to prepare a container with everything needed to run FABulous
+
+inputs:
+  python_version:
+    description: "Python version to use"
+    required: false
+    default: "3.12"
+  oss-cad-suite-nightly:
+    description: "Set true to use nightly version of oss-cad-suite."
+    required: false
+    default: "false"
+  additional_system_packages:
+    description: "Additional ubuntu packages to install"
+    required: false
+    default: ""
+  additional_python_packages:
+    description: "Additional python packages to install"
+    required: false
+    default: ""
+  install_ghdl_mcode:
+    description:
+      "If false, ghdl mcode won't be installed and the oss-cad-suite llvm
+      version is used"
+    required: false
+    default: "true"
+  install_nvc:
+    description: "If true, NVC VHDL simulator will be installed (recommended, faster than GHDL)"
+    required: false
+    default: "true"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python_version }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "latest"
+        enable-cache: true
+    - name: Get OSS CAD Suite version
+      id: oss-cad-version
+      shell: bash
+      run: |
+        # Get the latest release info from YosysHQ/oss-cad-suite-build
+        # Use authenticated API call to avoid rate limits
+
+        if ${{ inputs.oss-cad-suite-nightly }}; then
+          echo "Get latest oss-cad-suite nightly version"
+          if [ -n "${{ github.token }}"]; then
+            VERSION=$(curl -s -H "Authorization: Bearer ${{ github.token }}" \
+              "https://api.github.com/repos/YosysHQ/oss-cad-suite-build/releases/latest" | \
+              jq -r '.tag_name // "unknown"')
+          else
+            VERSION=$(curl -s "https://api.github.com/repos/YosysHQ/oss-cad-suite-build/releases/latest" | \
+              jq -r '.tag_name // "unknown"')
+          fi
+
+          # Fallback to a fixed version if API call fails
+          if [ "$VERSION" = "unknown" ] || [ "$VERSION" = "null" ] || [ -z "$VERSION" ]; then
+            echo "Warning: Failed to get OSS CAD Suite version from API, using fallback"
+            VERSION="2026-05-12"  # Use a recent stable version as fallback
+          fi
+
+        else
+          echo "Get latest known working OSS CAD Suite version."
+          VERSION="2026-05-12"  # Use a recent stable version as fallback
+        fi
+
+        echo "Using OSS CAD Suite version: $VERSION"
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+    - name: Cache OSS CAD Suite
+      id: cache-oss-cad
+      uses: actions/cache@v6
+      with:
+        path: |
+          ${{ runner.temp }}/oss-cad-suite
+        key: oss-cad-suite-${{ runner.os }}-${{ steps.oss-cad-version.outputs.version }}
+        restore-keys: |
+          oss-cad-suite-${{ runner.os }}-${{ steps.oss-cad-version.outputs.version }}
+    - name: set up OSS CAD path
+      if: ${{ steps.cache-oss-cad.outputs.cache-hit == 'true' }}
+      shell: bash
+      run: |
+        echo "${{ runner.temp }}/oss-cad-suite/bin:$PATH" >> "$GITHUB_PATH"
+    - name: Set up OSS CAD suite
+      if: ${{ steps.cache-oss-cad.outputs.cache-hit != 'true' }}
+      uses: YosysHQ/setup-oss-cad-suite@v4
+      with:
+        github-token: ${{ github.token }}
+        version: ${{ steps.oss-cad-version.outputs.version }}
+    - name: Install NVC VHDL simulator
+      uses: nickg/setup-nvc@v1
+      if: ${{ inputs.install_nvc != 'false' }}
+    - name: Install GHDL mcode nightly
+      # GHDL mcode is required to test our fabric.
+      # The oss-cad-suite action installs GHDL, but with the LLVM backend, which is much slower for our simulation
+      uses: ghdl/setup-ghdl@v1
+      if: ${{ inputs.install_ghdl_mcode != 'false' }}
+      with:
+        version: 6.0.0
+        backend: mcode
+        investigate: true
+    - name: Install additional ubuntu packages
+      if: ${{ inputs.additional_system_packages != '' }}
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y ${{ inputs.additional_system_packages }}
+    - name: Install additional python packages
+      if: ${{ inputs.additional_python_packages != '' }}
+      shell: bash
+      run: |
+        uv add ${{ inputs.additional_python_packages }}
+    - name: Install FABulous with dev dependencies
+      shell: bash
+      run: |
+        uv sync --dev --locked --all-extras
+        uv pip install -e .
+    - name: Set PATH
+      shell: bash
+      run: |
+        echo "$GITHUB_WORKSPACE/.venv/bin:/usr/local/bin:/usr/bin:/bin" >> "$GITHUB_PATH"

fabulous_fpga-2/.github/actions/prepare_nix_environment/action.yaml

@@ -0,0 +1,52 @@
+name: Prepare Nix environment
+description: Composite action to install Nix, cache the store, free disk space,
+  and build the devshell
+
+inputs:
+  nix_version:
+    description: "Nix version to install"
+    required: false
+    default: "2.34.7"
+  free_disk_space:
+    description: "Remove large pre-installed tool directories to free disk space"
+    required: false
+    default: "true"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Nix
+      uses: nixbuild/nix-quick-install-action@v35
+      with:
+        nix_version: ${{ inputs.nix_version }}
+        nix_conf: |
+          substituters = https://cache.nixos.org https://nix-cache.fossi-foundation.org
+          extra-trusted-public-keys = nix-cache.fossi-foundation.org:3+K59iFwXqKsL7BNu6Guy0v+uTlwsxYQxjspXzqLYQs=
+
+    - name: Free up disk space
+      if: ${{ inputs.free_disk_space == 'true' && runner.os == 'Linux' }}
+      shell: bash
+      run: |
+        sudo rm -rf /usr/share/dotnet
+        sudo rm -rf /usr/local/lib/android
+        sudo rm -rf /opt/ghc
+        sudo rm -rf /opt/hostedtoolcache
+        sudo rm -rf /usr/local/share/boost
+        sudo rm -rf /usr/lib/jvm
+        sudo rm -rf /usr/share/swift
+
+    - name: Cache Nix store
+      uses: nix-community/cache-nix-action@v7
+      with:
+        primary-key: nix-${{ runner.os }}-${{ hashFiles('flake.nix', 'flake.lock') }}
+        restore-prefixes-first-match: nix-${{ runner.os }}-
+        gc-max-store-size-linux: 10G
+        purge: true
+        purge-prefixes: nix-${{ runner.os }}-
+        purge-created: 0
+        purge-last-accessed: 0
+        purge-primary-key: never
+
+    - name: Build nix environment
+      shell: bash
+      run: nix develop --command true

fabulous_fpga-2/.github/copilot-instructions.md

@@ -0,0 +1,56 @@
+# AGENTS.md
+
+## Project Overview
+
+FABulous is a parametric FPGA fabric generator. It takes a fabric definition (CSV or YAML), builds an in-memory fabric model, and emits the HDL, nextpnr chip database, synthesis scripts, geometry, and bitstream needed to target that fabric.
+
+```text
+config (CSV/YAML) → fabric model → HDL + chip DB + synth scripts
+user design → Yosys (synth) → nextpnr (P&R) → FASM → bitstream
+```
+
+## How to Work in This Repo
+
+- **Python deps: `uv`.** Run `uv sync` after pulling; add deps with `uv add` (`--group dev` for dev-only). Never hand-edit `uv.lock`. Run commands as `uv run <cmd>` or activate `.venv/`.
+- **EDA toolchain: Nix.** `flake.nix` pins Yosys, nextpnr, OpenROAD, GHDL, Librelane, etc. The **GDS / ASIC flow** (anything under `gds_flow_test`, `librelane_plugin_fabulous`, or `fabulous/fabric_generator/gds_generator`) requires the Nix shell — `nix develop` first, when inside the shell you will not need `uv`. Don't try to substitute system installs of these tools; CI uses Nix and version drift will burn you.
+- **Tasks**: `Taskfile.yml` is the canonical runner. The ones you'll use most: `task test` (forwards args after `--`; pass `--runslow` for slow tests), `task ci` (run before pushing), `task smoke-test` (end-to-end). `task --list` for the rest.
+- **Pre-commit is enforced** (ruff, docstring linting, dependency hygiene, etc.). If a hook fails, fix the cause — don't `--no-verify`.
+
+## Coding Taste
+
+Rules that make changes feel native. Follow them even when a tool's defaults disagree.
+
+### Style
+
+- **Python 3.12+**. Built-in generics only (`list[int]`, `X | None`); never `typing.List`/`Optional`.
+- **Paths**: `pathlib.Path`. Never `os.path` or string concatenation.
+- **Logging**: `loguru` (`from loguru import logger`). Not `print`, not stdlib `logging`.
+- **Docstrings**: NumPy style — `pydoclint` + `interrogate` (≥95% coverage) enforce this.
+- **Inline code in docstrings/comments**: We use MyST for documentation. We use single "`" for raw text and "_" for italic.
+- **Naming**: this repo right now uses `camelCase` for variables/functions, `PascalCase` for classes, `CONSTANT_CASE` for module constants. Use snake case for all newly created methods and variables as we slow transition to meet PEP 8.  
+- Formatting (line length, quotes, etc.) is whatever `ruff format` produces.
+
+### Design
+
+- **No fallbacks, no silent retries.** Surface failures with clear errors. A stack trace beats a wrong result.
+- **Fix root causes.** If a fix doesn't change behavior the way you expected, stop and re-analyze before patching again.
+- **Validate at boundaries, trust internals.** Defensive checks belong where untrusted input enters (parsers, CLI, external tools).
+- **No premature abstraction.** Three similar lines beat a speculative helper. Ship the smallest correct change.
+- **Clear over clever.** Loops over unreadable comprehensions; parsers over paragraph-long regexes.
+- **Comments explain *why*, not *what*.** Reserve them for hidden constraints, non-obvious invariants, bug-specific workarounds. Don't reference task numbers or callers — that rots.
+- **Pydantic** for runtime-validated config (`fabulous_settings.py`); **dataclasses** for the fabric model — keep them light, no heavy logic.
+
+### Testing
+
+- `pytest` + `pytest-mock` (use the `mocker` fixture; don't import `unittest.mock`).
+- Mark slow tests `@pytest.mark.slow` so default `task test` stays fast.
+- Prefer real in-memory fabric fixtures over heavy mocks.
+- `cocotb` is available for RTL-level verification, not for Python logic.
+- Try to reuse fixture as much as possible.
+- Try to parameterize the test if possible
+
+## House Rules
+
+- Don't edit the symlinked agent files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`) — edit `AGENTS.md`.
+- Don't add new top-level packages without a clear home in the layout above.
+- When in doubt, read `Taskfile.yml`, `pyproject.toml`, and `tests/conftest.py` — they encode the live conventions. The Sphinx docs under `docs/` cover user-facing flow.