booley-rtl 0.1.0__tar.gz

booley_rtl-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an in-touch with
+      your own legal counsel to ensure the license is appropriate for your
+      jurisdiction and use case.
+
+   Copyright 2025-2026 The Booley Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

booley_rtl-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: booley-rtl
+Version: 0.1.0
+Summary: Orchestrated RTL development harness with ticket-based workflow automation
+Author-email: "A.R." <boldaxolotl@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/boldaxolotl/Booley
+Project-URL: Issues, https://github.com/boldaxolotl/Booley/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: claude-agent-sdk>=0.1.55
+Requires-Dist: click>=8.0
+Requires-Dist: colorama>=0.4
+Requires-Dist: edalize==0.6.8
+Requires-Dist: fusesoc==2.4.6
+Requires-Dist: httpx>=0.28
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: libcst>=1.0
+Requires-Dist: markdown-it-py>=4.0
+Requires-Dist: mcp>=1.8
+Requires-Dist: mdit-py-plugins>=0.5
+Requires-Dist: mutmut>=3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: setproctitle>=1.3
+Requires-Dist: textual>=8.0
+Requires-Dist: pywin32>=300; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# Booley
+
+**Agentic RTL development framework — sandboxed EDA flows driven by AI agents**
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+It's 2026, and LLMs are finally good enough to do real work. Software already accepts this: agents write more and more of the code while humans move up to architecture, specification, review, and integration. Hardware moves slower, but it moves: every major EDA vendor and a wave of startups are shipping AI tools for chip design. Those tools are closed, expensive, and out of reach if you don't work at a big company. I hit that wall myself, and raw agents like Claude Code and Codex kept failing on RTL work in the same predictable ways. So I built the tool I was missing: free and open source.
+
+The idea:
+
+1. Take the most capable coding agents available (Claude Code, Codex).
+2. Put them in a sandbox with the repo under development, blocking access to the host, so they can run without asking for permissions.
+3. Give them quick, one-command access to an open-source sim/lint/synth/waveform stack inside the sandbox, so they can check their own work and iterate fast.
+4. Wrap it all in one IDE: VS Code.
+
+A harness checks the agent's claims against real tool results (see below for the protection measures), and you choose how to drive it: hands-on in a chat, or hand it a self-contained ticket and let it run.
+
+
+## What Booley Solves
+
+Dropping a capable model into an RTL repo is not enough. I tried it. The toolchain is fragmented (every EDA tool speaks its own CLI, every coding agent its own protocol), and even once that's unified, a handful of failure modes make naive agentic hardware work unreliable. Booley puts one interface over every tool and every agent, then hardens it against the failure modes below.
+
+### A fragmented toolchain, one interface
+
+An RTL flow is a pile of tools that share nothing: Verilator, Icarus, Yosys, plus licensed heavyweights like Vivado or Xcelium, each with its own CLI, flags, and output format. The agent driving them is a moving part too: today Claude Code, tomorrow Codex. Wire an agent straight into that mess and you get N tools × M agents of brittle glue. Booley collapses it to one:
+
+- **One typed surface over every tool**: every EDA tool is a B-Tool: the same structured call in, the same normalized verdict out, whether it runs in the sandbox (Verilator, Icarus, Yosys, sv2v, `bwave`) or crosses the adapter boundary to a licensed tool on the host (Vivado, Xcelium, VCS). The agent learns one interface, not one per tool ([details](docs/FEATURES.md#structured-b-tool-contracts)).
+- **Agent-agnostic**: the same B-Tools are exposed over MCP, which Claude Code and Codex both drive natively. Pick the model you want; the toolchain stays identical ([details](docs/WHY.md#why-vs-code)).
+- **One environment**: editor, tools, and agent share a single VS Code window. No context switch between where you write RTL and where you run it: that's what makes VS Code the *agentic RTL IDE* the toolchain never had.
+
+### Hallucination and unreliability
+
+Left to its own judgment, an agent will declare a task done that it never finished, "pass" a test by misreading a log, or quietly run the wrong configuration. I've watched all three happen. Booley replaces the agent's judgment with machine-checked facts:
+
+- **Config and test registry**: `config` and `test` arguments resolve to named entries in Booley's shared configuration, not ad-hoc command lines. A request to run one test resolves to exactly that test, and the report carries the resolved identity, so the agent can't fool itself about what ran ([details](docs/FEATURES.md#named-build-configurations-and-tests)).
+- **Acceptance criteria**: Ticket Mode drives toward explicit criteria (`sim_pass`, `lint_clean`, `synthesis_pass`), and the ticket cannot complete until the harness, not the agent, confirms every mandatory one ([details](docs/USAGE.md#acceptance-criteria)).
+- **Structured tool contracts (B-Tools)**: a tool call returns a normalized verdict (`pass` / `fail` / `inconclusive` / `timeout`) instead of raw terminal output for the agent to (mis)interpret. A criterion is satisfied only when the tool itself returns a valid `pass` ([details](docs/FEATURES.md#structured-b-tool-contracts)).
+
+### You can't let an agent loose on your machine
+
+Autonomous work only pays off when the agent doesn't stop to ask permission at every step. But I'm not giving a capable, fallible model that's steerable by whatever text it reads free rein on my machine. The sandbox turns each failure mode into a contained non-event:
+
+- **Prompt injection**: text in a datasheet or web page hijacks the agent. Trapped in a container with no host access or general internet, the payload has nowhere to reach.
+- **Off-script pushes**: the agent drifts and "helpfully" commits half-finished work. It only touches an isolated worktree behind a human review-and-merge gate, never your remotes or real branches.
+- **Accidental damage**: a misfired `rm` or a script in the wrong directory. With only the worktree mounted, the blast radius stops at the sandbox.
+
+That's what makes "let it run autonomously" a sane default instead of a gamble:
+
+- **Sandboxed by default**: agents run in a container with only the worktree mounted: full autonomy inside, zero host access, network restricted to LLM API endpoints ([details](docs/FEATURES.md#docker-sandboxing)).
+- **Tools run inside too**: the sandbox image ships the EDA stack (Verilator, Icarus Verilog, Yosys, sv2v, bwave), so the common flows execute fully contained.
+- **A safe boundary for heavyweights**: when a tool is too heavy or too licensed to containerize (Vivado, vendor simulators), it runs on the host behind a narrow adapter interface, and Booley still sees the same tool contract ([details](docs/BTOOL-ADAPTER-CONTRACTS.md)).
+
+### Context rot
+
+Long single-context agent sessions degrade: the model loses the thread, gets distracted by stale logs, and quality falls off over a multi-hour task.
+
+- **Specialists with isolated context**: each Specialist (testbench authoring, code review, mutation testing) runs in a fresh LLM context, so none of them drags along stale logs or drafts from earlier iterations. The orchestrator carries continuity through structured state, not an ever-growing conversation ([details](docs/ARCHITECTURE.md#the-sandbox)).
+
+### Debugging blind
+
+A waveform is how a hardware engineer actually debugs. But an LLM can't read a multi-gigabyte VCD, so without one the agent is reduced to guessing about the code. So I wrote it a waveform tool:
+
+- **Waveform-aware debug (`bwave`)**: a Rust tool that lets the agent query signal values over time ranges, trigger sampling of one signal on another, and trace data through the design, debugging from observed behavior, not speculation. The simulator streams its VCD through an in-RAM FIFO that `bwave` compacts into a `.bwave` cache on the fly, so the multi-gigabyte VCD never touches disk; even 10 GB+ traces stay tractable and the tracing overhead stays small ([details](docs/FEATURES.md#waveform-based-debug)).
+
+### Weak testbenches
+
+Agents work best against a concrete criterion. For RTL that criterion is the testbench: the agent writes and fixes the design until the testbench passes. But nothing judges the *testbench*: a weak one passes no matter what, and a green run tells you nothing about whether the design was actually exercised.
+
+- **Mutation testing**: Booley injects targeted bugs into the RTL and checks whether the testbench catches them, scoring the detection rate against a threshold. "Tests pass" becomes "tests pass *and* are proven to catch real bugs." The testbench is the RTL's criterion; mutation testing is the testbench's ([details](docs/FEATURES.md#mutation-testing)).
+
+Booley does much more than this: coverage measurement, multi-phase code review, automated SVA generation, lint triage, scope enforcement, and more. See [FEATURES.md](docs/FEATURES.md) for the full list.
+
+## Modes of Operation
+
+Two modes, same project configuration, same tool stack, same per-folder sandbox container (the Session Runtime), just two ways to drive it.
+
+### Interactive Mode
+
+The hands-on path. Open your RTL repo in VS Code, accept **"Reopen in Container"**, and the window reloads inside a Booley runtime container with everything it needs: simulators, lint, synthesis, waveform tools, and the specialist agents. The container comes from an untracked `.devcontainer/devcontainer.json` that `booley init` writes into the repo (hidden from git via `.git/info/exclude`, never committed). Egress is restricted to a Booley proxy, the agent runs as a non-root user, and an idle reaper stops orphaned sessions.
+
+From there you just chat: what to inspect, which simulation to run, what failure to debug, what code to review, which waveform to query. You guide the work closely and make decisions as they come up. (`booley_status` at the start of a session shows the sandbox container id and available tools.)
+
+### Ticket Mode
+
+The autonomous path. You write a ticket (the ticket-creation skill helps) specifying what needs doing, which files are in scope, which tests must pass, and any other completion criteria. Then `booley run` from a terminal inside the devcontainer, one terminal per concurrent ticket alongside your interactive session, and Booley does the rest: isolated worktree, orchestrator, specialists, EDA tools, criteria tracking, all the way to completion.
+
+When the ticket reaches review, you inspect the result, adjust if needed, then approve and merge into your working branch.
+
+## Limitations
+
+- **Booley will not design hardware for you.** You design the architecture and write the specs; Booley handles the grunt work. Force multiplier, not replacement.
+- **Testbenches are simple and direct.** Plain SystemVerilog, no UVM.
+- **Only tested at the IP level.** Complex IPs, like a RISC-V core or crypto accelerators, but never chip- or SoC-level integration.
+- **Setup can take effort.** The setup skills make integration as smooth as I could get it, but every build system is different; complex flows or heavy licensed EDA tools may still need project-specific work.
+- **The code quality is "hardware engineer writing software."** The architecture is sound, but the Python could use polish. Contributions from actual software developers are very welcome.
+- **Work in progress.** Expect occasional bugs and rough edges in the UI. I'm actively on it, and things keep getting better.
+
+## Quick Start
+
+Three ways in, ordered by how much you want to invest:
+
+1. **[Level 1: Watch](#level-1--watch-2-min).** See an engineer drive Booley on a demo project, start to finish. Zero setup.
+2. **[Level 2: Try the demo yourself](#level-2--try-the-demo-yourself).** Clone a pre-configured demo repo and run its tickets out of the box.
+3. **[Level 3: Use it on your own project](#level-3--use-it-on-your-own-project).** Full integration on your own RTL.
+
+### Level 1 — Watch (2 min)
+
+> **Coming soon.** A short screencast of me driving Booley on a demo project end to end (feasibility triage, ticket run, results) so you can see the workflow before touching anything.
+
+### Level 2 — Try the demo yourself
+
+> **Demo repo coming soon.** A well-known open-source IP with pre-configured Booley tickets, ready to run out of the box: no `/booley-setup` needed, since the design description, tests, and config already ship in the repo. The steps below are the flow you'll follow once the link is live.
+
+The prerequisites and platform notes below apply to Levels 2 and 3 alike.
+
+**Supported platforms:** Windows (yes, you can now design hardware on Windows), Linux (Ubuntu 24.04 tested). macOS is not supported.
+
+> **Windows.** Booley runs **natively on Windows**: install the CLI with Windows Python, keep your repo on a normal `C:\...` path, and let **Docker Desktop** (WSL2 backend) host the containers: no WSL shell needed, no repo on the WSL filesystem. Three Windows-specific gotchas:
+> - **Python:** a fresh Windows has only the Microsoft Store *aliases* (`python`/`python3` open the Store instead of running). Install a real one first, e.g. `winget install Python.Python.3.13`.
+> - **Docker Desktop must be running**: its CLI only joins `PATH` once the app has started; open a new terminal after first launch.
+> - **Line endings:** Git for Windows defaults to `core.autocrlf=true`, which checks files out with CRLF; the Linux container then sees every file as modified. In your RTL repo set `git config core.autocrlf false`, commit a `.gitattributes` with `* text eol=lf`, and re-checkout (`git checkout -- .`). `booley init` detects and warns about this.
+
+> **EDA tool support.** First-class today: the open-source stack (Verilator, Icarus Verilog, Yosys, sv2v) plus **Vivado** for FPGA implementation: built-in flows, no extra work. **Cadence Xcelium** runs through a built-in host-boundary simulate backend (`builtin-host`) that loads your tool module and license on the host, validated end-to-end. Full picture in the [supported-tools matrix](docs/SUPPORTED-TOOLS.md); wire your own commercial flow via a [project-native host adapter](docs/CONFIG.md#project-native-backends), or track remaining Big-3 coverage (Design Compiler, Siemens) on the [roadmap](docs/ROADMAP.md#commercial-eda-backends).
+
+> **Synthesis is a PPA estimate, not tape-out.** The `asic_synthesize` B-Tool gives you **power/performance/area metrics fast enough to iterate the RTL against**, not a sign-off, whatever engine backs it (Yosys + OpenROAD today; Genus / Design Compiler may follow). Real tape-out synthesis (physical implementation, CTS, routing, DRC/LVS, multi-corner STA on a foundry PDK) is **out of scope for Booley**. See [SUPPORTED-TOOLS.md](docs/SUPPORTED-TOOLS.md#built-in-flows).
+
+**Prerequisites:**
+- **Python 3.11+**
+- **Docker**: hosts the sandbox and tool stack
+- **VS Code** with the **Dev Containers** extension: Booley runs inside a devcontainer via **Reopen in Container**
+- Credentials for at least one supported agent backend:
+  - **OpenAI / Codex** (default): a ChatGPT Plus subscription ($20/mo minimum) or an OpenAI API key
+  - **Anthropic / Claude**: a Claude Pro/Max subscription or an Anthropic API key
+
+Booley runs on a single provider; select it via `booley.toml [agent] provider` (`codex` or `claude`). Both the orchestrator and all specialists run on the chosen provider.
+
+> **Note:** Booley's agents authenticate the same way Claude Code or Codex do. A **subscription** (Claude Pro/Max or ChatGPT/Codex) covers **both** modes, including the nested Specialist agents. An **API key** is the pay-per-token alternative; if `ANTHROPIC_API_KEY` is set it takes precedence over a Claude subscription. Auth and billing details in [USAGE.md](docs/USAGE.md#ticket-mode--cli-reference).
+
+```bash
+# Install Booley
+pip install booley-rtl
+
+# Clone the pre-configured demo repo (link coming soon) and enter it
+git clone <demo-repo-url>
+cd <demo-repo>
+
+# Initialize Booley project state and seed the Interactive Mode devcontainer
+booley init
+```
+
+Then open the repo folder in VS Code and accept **Reopen in Container**. When the
+window reloads, the agent extension (Claude Code or Codex, whichever you picked
+during `booley init`) is already installed, chat panel in the sidebar. The demo
+ships its design description, tests, and tickets, so there's nothing to
+configure: run a shipped ticket straight from a terminal inside the container:
+
+```bash
+# Run an autonomous ticket end to end
+booley run --ticket <slug>
+```
+
+### Level 3 — Use it on your own project
+
+Same shape: `pip install booley-rtl`, `booley init`, **Reopen in Container**, but
+instead of shipped tickets you run the **`/booley-setup`** skill in the agent
+chat to onboard your own RTL: feasibility triage, `AGENTS.md`, FuseSoC `.core`
+design discovery, tests, config, and a final `booley doctor` audit. Then
+`booley run` your own tickets.
+
+> **Do you have to adopt FuseSoC?** The built-in flows build from a FuseSoC
+> `.core` target: the default, simplest path that fits most projects. If you'd
+> rather keep your existing build system (Makefile, vendor-simulator flow, custom scripts),
+> use a [project-native adapter](docs/CONFIG.md#project-native-backends): no `.core`
+> is required and you do not convert your build to FuseSoC.
+
+**Full walkthrough, including project-native adapters for commercial EDA flows,
+is in [SETUP.md](docs/SETUP.md).**
+
+## Documentation
+
+- [Features](docs/FEATURES.md): expanded descriptions of all capabilities
+- [Setup](docs/SETUP.md): installation, configuration, advanced backends
+- [Usage](docs/USAGE.md): CLI reference, ticket-driven workflow, acceptance criteria
+- [Architecture](docs/ARCHITECTURE.md): orchestrator, agentic tools, mechanical tools, context isolation
+- [Why](docs/WHY.md): the rationale behind the load-bearing decisions (Docker, VS Code, two modes, MCP)
+- [Benchmarks](docs/BENCHMARKS.md): results and comparison with related work
+- [Roadmap](docs/ROADMAP.md): planned features and future directions
+
+## Contributing
+
+Contributions welcome. See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
+
+## Acknowledgments
+
+Booley stands on a lot of other people's work. Thank you to:
+
+- **The authors of [Edalize](https://github.com/olofk/edalize) and [FuseSoC](https://github.com/olofk/fusesoc)**, and especially their lead maintainer, Olof Kindgren, for the framework that makes Booley's whole idea of a simple, unified CLI-over-EDA interface possible.
+- **The author of [vcdvcd](https://github.com/cirosantilli/vcdvcd), Ciro Santilli**, for the VCD-parsing work that seeded the `bwave` idea.
+- **The author of [wavepeek](https://github.com/kleverhq/wavepeek)**, another neat waveform-to-CLI tool, for the clean top-level CLI interface that inspired `bwave`'s (the internals started well before wavepeek and are quite different).
+- **The authors of [Yosys](https://github.com/YosysHQ/yosys), [Verilator](https://github.com/verilator/verilator), [Icarus Verilog](https://github.com/steveicarus/iverilog), and [sv2v](https://github.com/zachjs/sv2v)**, for the excellent open-source EDA tools that make Booley possible at all.
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE) for details.