fabricgate 0.1.0__tar.gz

fabricgate-0.1.0/.editorconfig

@@ -0,0 +1,25 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yaml,yml,json,toml}]
+indent_size = 2
+
+[*.{js,jsx,ts,tsx,css}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[Dockerfile*]
+indent_style = space
+indent_size = 4

fabricgate-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

fabricgate-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,94 @@
+name: CI
+
+# Public CI: lint, type-check, unit tests, build + publication-boundary
+# check, dependency audit. No secrets are used anywhere in this workflow.
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+  workflow_call:
+    inputs:
+      force_all:
+        description: "Kept for release.yaml compatibility; every job always runs here"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check (ruff / mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: ".python-version"
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    env:
+      # Overrides .python-version so both uv sync and uv run use the matrix
+      # interpreter; otherwise uv run re-creates the venv with 3.11 and drops
+      # the dev group.
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen
+      - run: uv run pytest -q --cov=fabricgate --cov-report=term-missing
+
+  build:
+    name: Build & boundary check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - run: uv build
+      - name: Enforce publication boundary (no registry code in wheel/sdist)
+        run: |
+          set -euo pipefail
+          for whl in dist/*.whl; do
+            python3 -m zipfile --list "$whl" | grep -q "fabricgate/registry/" && { echo "::error::$whl contains fabricgate/registry/"; exit 1; }
+          done
+          for sdist in dist/*.tar.gz; do
+            tar -tzf "$sdist" | grep -q "fabricgate/registry/" && { echo "::error::$sdist contains fabricgate/registry/"; exit 1; }
+          done
+          echo "boundary OK"
+      - name: Smoke-install the wheel
+        run: |
+          python3 -m venv /tmp/smoke && /tmp/smoke/bin/pip install -q dist/*.whl
+          /tmp/smoke/bin/fabricgate --version && /tmp/smoke/bin/fgate --help > /dev/null
+
+  audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - run: uv sync --frozen
+      - run: uv run pip-audit
+
+  ci-success:
+    name: CI Success
+    if: always()
+    needs: [check, test, build, audit]
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo '${{ toJSON(needs) }}' | grep -qE '"result": "(failure|cancelled)"' && exit 1
+          echo "all green"

fabricgate-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,165 @@
+name: Release
+
+# Triggers:
+#   - push of a stable vX.Y.Z tag: full release (PyPI + attestation + GitHub Release)
+#     Pre-release / staging tags (v0.1.0-staging.N) are handled by cd.yaml only;
+#     they would always fail the version guard below, so Release ignores them.
+#   - workflow_dispatch: TestPyPI dry-run (no GitHub Release)
+#
+# Prerequisites (one-time, human):
+#   - PyPI / TestPyPI Trusted Publisher registered for this repo
+#     (workflow=release.yaml, environment=pypi / testpypi)
+#   - GitHub environments `pypi` and `testpypi` created
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch: # TestPyPI dry-run
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: CI Gate
+    # ci.yaml declares `pull-requests: read`; a called workflow cannot request
+    # more than the calling job holds, so grant it explicitly here. Without
+    # this GitHub refuses to start the run at all (startup_failure, 0 jobs).
+    permissions:
+      contents: read
+      pull-requests: read
+    uses: ./.github/workflows/ci.yaml
+    with:
+      # In reusable workflows the `github` context is the caller's, so
+      # ci.yaml's paths-filter sees an empty diff on tag pushes and would
+      # skip every job. Force the full gate instead.
+      force_all: true
+    secrets: inherit
+
+  build:
+    name: Build public package
+    runs-on: ubuntu-latest
+    needs: [ci]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      - name: Verify tag matches package version
+        if: github.event_name == 'push'
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::tag v$TAG_VERSION != pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Use a unique dev version for TestPyPI dry-runs
+        # TestPyPI never lets a deleted filename be reused, so every dry-run
+        # publishes <version>.dev<run_number>. Tag pushes keep the real version.
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          set -euo pipefail
+          BASE=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          DEV="${BASE}.dev${GITHUB_RUN_NUMBER}"
+          uv version --frozen "$DEV"
+          sed -i "s/^__version__ = \".*\"$/__version__ = \"${DEV}\"/" src/fabricgate/_version.py
+          grep -q "\"${DEV}\"" src/fabricgate/_version.py
+          echo "dry-run version: ${DEV}"
+
+      - name: Build
+        run: uv build
+
+      - name: Enforce publication boundary (no registry code in wheel/sdist)
+        # Capture listings before grepping so a failed listing (missing
+        # artifact, unreadable archive) fails the step instead of being
+        # swallowed by the pipe inside the `if` condition.
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          wheels=(dist/*.whl)
+          sdists=(dist/*.tar.gz)
+          if [ "${#wheels[@]}" -eq 0 ] || [ "${#sdists[@]}" -eq 0 ]; then
+            echo "::error::expected at least one wheel and one sdist in dist/ (found ${#wheels[@]} wheel(s), ${#sdists[@]} sdist(s))"
+            exit 1
+          fi
+          for whl in "${wheels[@]}"; do
+            listing=$(python3 -m zipfile --list "$whl")
+            if grep -q "fabricgate/registry/" <<<"$listing"; then
+              echo "::error::wheel $whl contains fabricgate/registry/ — distribution-policy P-2 violation"
+              exit 1
+            fi
+          done
+          for sdist in "${sdists[@]}"; do
+            listing=$(tar -tzf "$sdist")
+            if grep -q "fabricgate/registry/" <<<"$listing"; then
+              echo "::error::sdist $sdist contains fabricgate/registry/ — distribution-policy P-2 violation"
+              exit 1
+            fi
+          done
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to ${{ github.event_name == 'workflow_dispatch' && 'TestPyPI' || 'PyPI' }}
+    runs-on: ubuntu-latest
+    needs: [build]
+    environment: ${{ github.event_name == 'workflow_dispatch' && 'testpypi' || 'pypi' }}
+    permissions:
+      id-token: write # OIDC trusted publishing
+      attestations: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Attest build provenance
+        # GitHub does not store attestations for user-owned *private* repos
+        # ("Feature not available for user-owned private repositories").
+        # Tolerate that on TestPyPI dry-runs so the publish path can still be
+        # rehearsed before the repo goes public; a real release (tag push)
+        # must ship provenance and therefore still fails loudly here.
+        continue-on-error: ${{ github.event_name == 'workflow_dispatch' }}
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: "dist/*"
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: ${{ github.event_name == 'workflow_dispatch' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
+          # TestPyPI rejects re-uploads of the same version; tolerate them
+          # on dry-runs only so repeated dispatches don't fail. Real PyPI
+          # releases (tag push) must still fail loudly on a duplicate.
+          skip-existing: ${{ github.event_name == 'workflow_dispatch' }}
+
+  release:
+    name: GitHub Release
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs: [publish]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --generate-notes dist/*

fabricgate-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+coverage.lcov
+htmlcov/
+.mypy_cache/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+
+
+
+# VSCode — keep shared settings, ignore user-specific files
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/launch.json
+!.vscode/tasks.json
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node.js (frontend)
+
+# Alembic
+*.db
+
+# Docker
+docker-compose.override.yaml
+docker-compose.override.yml
+
+# Local diagnostics
+.diagnostics/
+.vite/
+
+# Project review reports
+docs/report/
+tmp/
+
+# FPGA test fixture binaries (generated or downloaded — not committed)
+tests/fixtures/binaries/
+!tests/fixtures/binaries/.gitkeep

fabricgate-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

fabricgate-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to FabricGate (CLI/SDK)
+
+Thanks for your interest. This repository holds the public client side of FabricGate: the CLI, the Python SDK, the shared models and the API contracts. Bug reports, board additions, documentation fixes and features are all welcome.
+
+## Development setup
+
+```sh
+git clone https://github.com/harurun78/fabricgate.git
+cd fabricgate
+uv sync                       # https://docs.astral.sh/uv/  (installs the dev group too)
+uv run fabricgate --help
+```
+
+Python 3.11+ is required. `uv.lock` is committed; CI installs with `--frozen`, so run `uv lock` when you change dependencies.
+
+## Checks that CI runs
+
+```sh
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run pytest -q
+uv build
+```
+
+All of them must pass before a pull request is merged. Tests live in `tests/unit/`; fixtures in `tests/fixtures/`.
+
+## Changing the API contracts
+
+`docs/contracts/` is the source of truth for the registry's public API. The wire-format JSON Schemas are generated from the models:
+
+```sh
+uv run python scripts/extract_schemas.py
+```
+
+Commit the regenerated files together with the model change and add an entry to `docs/contracts/CHANGELOG.md`. Breaking changes to the *read* API are not accepted without a migration note; the write API is still marked MVP and may change.
+
+## Adding a board to the Board DB
+
+Boards live in `src/fabricgate/data/board-db/official.yaml` and are validated against `docs/contracts/schemas/board-db.schema.json` (`tests/unit/test_models.py`). Add an entry with `board_id`, `device`, the supported runtimes and a source URL for the identification data, and open a pull request. No code change is needed.
+
+## Pull requests
+
+- One purpose per pull request; keep unrelated refactors out.
+- Conventional Commits for titles (`feat(cli): ...`, `fix(sdk): ...`, `docs: ...`).
+- Describe how you verified the change. Screenshots are not needed; command output is.
+- Do not add secrets, tokens or personal data to tests, fixtures or CI. The workflows in this repository run without any secrets by design.
+- Please reference issues from **this** repository only. The registry implementation is developed elsewhere; if a change here depends on a server-side change, describe it in words rather than linking an internal issue number.
+
+## Reporting bugs
+
+Open an issue with the `fabricgate --version` output, the command you ran, and the full error text (`--verbose` helps). Security problems go to the address in [SECURITY.md](SECURITY.md), not to the issue tracker.

fabricgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FabricGate 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.

fabricgate-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: fabricgate
+Version: 0.1.0
+Summary: FabricGate CLI/SDK — discover, pull and verify FPGA designs across boards and runtimes
+Project-URL: Homepage, https://github.com/harurun78/fabricgate
+Project-URL: Source, https://github.com/harurun78/fabricgate
+Project-URL: Issues, https://github.com/harurun78/fabricgate/issues
+Project-URL: Changelog, https://github.com/harurun78/fabricgate/blob/master/docs/contracts/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: bitstream,cli,fpga,pynq,registry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Requires-Dist: click>=8.3.3
+Requires-Dist: cryptography>=50.0.0
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: email-validator>=2.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# FabricGate
+
+[![CI](https://github.com/harurun78/fabricgate/actions/workflows/ci.yaml/badge.svg)](https://github.com/harurun78/fabricgate/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Discover, pull and verify FPGA designs for your board — one command, any runtime.**
+
+FabricGate is a package registry for FPGA designs (bitstreams plus the metadata a runtime needs to load them). This repository contains the client side: the `fabricgate` CLI, the Python SDK, the shared data models, and the public API contracts. The hosted registry lives at `https://registry.fabricgate.dev`.
+
+> **Status: alpha.** The registry is being seeded with community PYNQ overlays. Interfaces marked *stable* in `docs/specs/` are kept backward compatible; everything else may still change before 1.0.
+
+## Install
+
+```sh
+pip install fabricgate
+```
+
+Python 3.11 or newer. `fgate` is installed as a short alias of `fabricgate`.
+
+## Three steps to a running design
+
+```sh
+# 1. Find a design for your board
+fabricgate search --platform pynq-z2/pynq adder
+
+# 2. Pull it (bitstream + hwh + manifest, digests verified on download)
+fabricgate pull example/adder-demo:1.0.0 --platform pynq-z2/pynq
+
+# 3. Load it with the runtime you already use
+python -c "from pynq import Overlay; ol = Overlay('adder-demo/adder.bit')"
+```
+
+`example/adder-demo` is a placeholder name; run `fabricgate search` to see what is actually published. The `--platform` value is `<board>/<runtime>`; run `fabricgate pull --help` for the resolution rules, including the `generic-<device>` fallback.
+
+## What the CLI can do
+
+| Command | Purpose |
+|---|---|
+| `search`, `info`, `diff`, `stats`, `watch` | discover designs and track updates |
+| `pull`, `verify`, `list` | download with digest verification, re-verify, inspect the local cache |
+| `build`, `push`, `yank`, `deprecate` | publish your own designs (`build` generates the Platform Manifest and Design Index from a build directory) |
+| `login`, `token`, `quota`, `webhook`, `license-check` | account, automation and policy helpers |
+
+`fabricgate --json` gives machine-readable output for every command.
+
+## Supported boards and runtimes
+
+The bundled Board DB (`src/fabricgate/data/board-db/official.yaml`) currently knows these boards:
+
+| Board | Device | Runtime |
+|---|---|---|
+| `pynq-z2` | xc7z020 | `pynq` |
+| `zcu104` | xczu7ev | `pynq`, `linux-fpgamgr` |
+| `pico-ice` | iCE40UP5K | `nanopynq` (Phase 3, forward reference) |
+| `generic-xc7z020`, `generic-xczu7ev` | — | device-level fallback for boards not yet listed |
+
+Adding a board is a data change; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## SDK
+
+```python
+from fabricgate.sdk import api
+
+result = api.pull("example/adder-demo:1.0.0", platform="pynq-z2/pynq")
+print(result.artifacts)
+```
+
+The SDK wraps the same client the CLI uses. See `docs/specs/client-behavior.md` for the resolution and caching rules.
+
+## Public contracts
+
+`docs/contracts/` is the source of truth for the registry's public API:
+
+- `openapi.yaml` / `openapi.json` — Registry HTTP API
+- `schemas/design-index.schema.json`, `schemas/platform-manifest.schema.json`, `schemas/board-db.schema.json` — wire formats
+- `CHANGELOG.md` — contract changes and migration notes
+
+Specifications for the CLI, client behaviour and data formats are in `docs/specs/`.
+
+## Self-hosting and the registry implementation
+
+The registry server is operated as a hosted service and its implementation is not published at this stage (see `docs/specs/` for the distribution policy summary in `client-behavior.md`). Everything a client needs to interoperate — API, schemas, error formats — is in this repository, so alternative implementations are possible.
+
+## Contributing, security, license
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, tests, pull requests
+- [SECURITY.md](SECURITY.md) — how to report a vulnerability
+- [LICENSE](LICENSE) — MIT

fabricgate-0.1.0/README.md

@@ -0,0 +1,88 @@
+# FabricGate
+
+[![CI](https://github.com/harurun78/fabricgate/actions/workflows/ci.yaml/badge.svg)](https://github.com/harurun78/fabricgate/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Discover, pull and verify FPGA designs for your board — one command, any runtime.**
+
+FabricGate is a package registry for FPGA designs (bitstreams plus the metadata a runtime needs to load them). This repository contains the client side: the `fabricgate` CLI, the Python SDK, the shared data models, and the public API contracts. The hosted registry lives at `https://registry.fabricgate.dev`.
+
+> **Status: alpha.** The registry is being seeded with community PYNQ overlays. Interfaces marked *stable* in `docs/specs/` are kept backward compatible; everything else may still change before 1.0.
+
+## Install
+
+```sh
+pip install fabricgate
+```
+
+Python 3.11 or newer. `fgate` is installed as a short alias of `fabricgate`.
+
+## Three steps to a running design
+
+```sh
+# 1. Find a design for your board
+fabricgate search --platform pynq-z2/pynq adder
+
+# 2. Pull it (bitstream + hwh + manifest, digests verified on download)
+fabricgate pull example/adder-demo:1.0.0 --platform pynq-z2/pynq
+
+# 3. Load it with the runtime you already use
+python -c "from pynq import Overlay; ol = Overlay('adder-demo/adder.bit')"
+```
+
+`example/adder-demo` is a placeholder name; run `fabricgate search` to see what is actually published. The `--platform` value is `<board>/<runtime>`; run `fabricgate pull --help` for the resolution rules, including the `generic-<device>` fallback.
+
+## What the CLI can do
+
+| Command | Purpose |
+|---|---|
+| `search`, `info`, `diff`, `stats`, `watch` | discover designs and track updates |
+| `pull`, `verify`, `list` | download with digest verification, re-verify, inspect the local cache |
+| `build`, `push`, `yank`, `deprecate` | publish your own designs (`build` generates the Platform Manifest and Design Index from a build directory) |
+| `login`, `token`, `quota`, `webhook`, `license-check` | account, automation and policy helpers |
+
+`fabricgate --json` gives machine-readable output for every command.
+
+## Supported boards and runtimes
+
+The bundled Board DB (`src/fabricgate/data/board-db/official.yaml`) currently knows these boards:
+
+| Board | Device | Runtime |
+|---|---|---|
+| `pynq-z2` | xc7z020 | `pynq` |
+| `zcu104` | xczu7ev | `pynq`, `linux-fpgamgr` |
+| `pico-ice` | iCE40UP5K | `nanopynq` (Phase 3, forward reference) |
+| `generic-xc7z020`, `generic-xczu7ev` | — | device-level fallback for boards not yet listed |
+
+Adding a board is a data change; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## SDK
+
+```python
+from fabricgate.sdk import api
+
+result = api.pull("example/adder-demo:1.0.0", platform="pynq-z2/pynq")
+print(result.artifacts)
+```
+
+The SDK wraps the same client the CLI uses. See `docs/specs/client-behavior.md` for the resolution and caching rules.
+
+## Public contracts
+
+`docs/contracts/` is the source of truth for the registry's public API:
+
+- `openapi.yaml` / `openapi.json` — Registry HTTP API
+- `schemas/design-index.schema.json`, `schemas/platform-manifest.schema.json`, `schemas/board-db.schema.json` — wire formats
+- `CHANGELOG.md` — contract changes and migration notes
+
+Specifications for the CLI, client behaviour and data formats are in `docs/specs/`.
+
+## Self-hosting and the registry implementation
+
+The registry server is operated as a hosted service and its implementation is not published at this stage (see `docs/specs/` for the distribution policy summary in `client-behavior.md`). Everything a client needs to interoperate — API, schemas, error formats — is in this repository, so alternative implementations are possible.
+
+## Contributing, security, license
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, tests, pull requests
+- [SECURITY.md](SECURITY.md) — how to report a vulnerability
+- [LICENSE](LICENSE) — MIT