velloo 0.0.0 → 0.2.0

package/BUN-LICENSE.md

@@ -0,0 +1,91 @@
+# Bun 1.4.2 license and linked-library notices
+
+The upstream notice below is vendored from the signed Bun 1.4.2 release:
+<https://github.com/oven-sh/bun/blob/bun-v1.4.2/LICENSE.md>.
+
+---
+
+Bun itself is MIT-licensed.
+
+## JavaScriptCore
+
+Bun statically links JavaScriptCore (and WebKit) which is LGPL-2 licensed. WebCore files from WebKit are also licensed under LGPL2. Per LGPL2:
+
+> (1) If you statically link against an LGPL’d library, you must also provide your application in an object (not necessarily source) format, so that a user has the opportunity to modify the library and relink the application.
+
+You can find the patched version of WebKit used by Bun here: <https://github.com/oven-sh/webkit>. If you would like to relink Bun with changes:
+
+- `git clone https://github.com/oven-sh/WebKit vendor/WebKit`
+- `bun sync-webkit-source` (checks out the version pinned in `WEBKIT_VERSION` in `scripts/build/deps/webkit.ts`)
+- `bun run build:local`
+
+This compiles JavaScriptCore, compiles Bun’s `.cpp` bindings for JavaScriptCore (which are the object files using JavaScriptCore) and outputs a new `bun` binary with your changes.
+
+## Linked libraries
+
+Bun statically links these libraries:
+
+| Library | License |
+|---------|---------|
+| [`boringssl`](https://boringssl.googlesource.com/boringssl/) | [several licenses](https://boringssl.googlesource.com/boringssl/+/refs/heads/master/LICENSE) |
+| [`brotli`](https://github.com/google/brotli) | MIT |
+| [`libarchive`](https://github.com/libarchive/libarchive) | [several licenses](https://github.com/libarchive/libarchive/blob/master/COPYING) |
+| [`lol-html`](https://github.com/cloudflare/lol-html/tree/master/c-api) | BSD 3-Clause |
+| [`ls-hpack`](https://github.com/litespeedtech/ls-hpack) | MIT |
+| [`ls-qpack`](https://github.com/litespeedtech/ls-qpack) | MIT |
+| [`lsquic`](https://github.com/litespeedtech/lsquic) | MIT (portions derived from [Chromium proto-quic](https://github.com/litespeedtech/lsquic/blob/master/LICENSE.chrome), BSD 3-Clause) |
+| [`mimalloc`](https://github.com/microsoft/mimalloc) | MIT |
+| [`picohttp`](https://github.com/h2o/picohttpparser) | dual-licensed under the Perl License or the MIT License |
+| [`zstd`](https://github.com/facebook/zstd) | dual-licensed under the BSD License or GPLv2 license |
+| [`simdutf`](https://github.com/simdutf/simdutf) | Apache 2.0 |
+| [`tinycc`](https://github.com/tinycc/tinycc) | LGPL v2.1 |
+| [`uSockets`](https://github.com/uNetworking/uSockets) | Apache 2.0 |
+| [`zlib-ng`](https://github.com/zlib-ng/zlib-ng) | zlib |
+| [`c-ares`](https://github.com/c-ares/c-ares) | MIT licensed |
+| [`libicu`](https://github.com/unicode-org/icu) 78 | [license here](https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE) |
+| [`libbase64`](https://github.com/aklomp/base64/blob/master/LICENSE) | BSD 2-Clause |
+| [`libuv`](https://github.com/libuv/libuv) (on Windows) | MIT |
+| [`libdeflate`](https://github.com/ebiggers/libdeflate) | MIT |
+| [`libjpeg-turbo`](https://github.com/libjpeg-turbo/libjpeg-turbo) | [BSD 3-Clause / IJG / zlib](https://github.com/libjpeg-turbo/libjpeg-turbo/blob/main/LICENSE.md) |
+| [`libspng`](https://github.com/randy408/libspng) | BSD 2-Clause |
+| [`libwebp`](https://github.com/webmproject/libwebp) | BSD 3-Clause |
+| [`highway`](https://github.com/google/highway) | Apache 2.0 |
+| [`uucode`](https://github.com/jacobsandlund/uucode) | MIT |
+| A fork of [`uWebsockets`](https://github.com/jarred-sumner/uwebsockets) | Apache 2.0 licensed |
+| Parts of [Tigerbeetle's IO code](https://github.com/tigerbeetle/tigerbeetle/blob/532c8b70b9142c17e07737ab6d3da68d7500cbca/src/io/windows.zig#L1) | Apache 2.0 licensed |
+| `__cxa_thread_atexit` fallback from [LLVM libc++abi](https://github.com/llvm/llvm-project/blob/llvmorg-19.1.0/libcxxabi/src/cxa_thread_atexit.cpp) | Apache 2.0 with LLVM exception |
+
+## Polyfills
+
+For compatibility reasons, the following packages are embedded into Bun's binary and injected if imported.
+
+| Package | License |
+|---------|---------|
+| [`acorn`](https://github.com/acornjs/acorn) | MIT |
+| [`acorn-walk`](https://github.com/acornjs/acorn) | MIT |
+| [`assert`](https://npmjs.com/package/assert) | MIT |
+| [`browserify-zlib`](https://npmjs.com/package/browserify-zlib) | MIT |
+| [`buffer`](https://npmjs.com/package/buffer) | MIT |
+| [`constants-browserify`](https://npmjs.com/package/constants-browserify) | MIT |
+| [`crypto-browserify`](https://npmjs.com/package/crypto-browserify) | MIT |
+| [`domain-browser`](https://npmjs.com/package/domain-browser) | MIT |
+| [`events`](https://npmjs.com/package/events) | MIT |
+| [`https-browserify`](https://npmjs.com/package/https-browserify) | MIT |
+| [`os-browserify`](https://npmjs.com/package/os-browserify) | MIT |
+| [`path-browserify`](https://npmjs.com/package/path-browserify) | MIT |
+| [`process`](https://npmjs.com/package/process) | MIT |
+| [`punycode`](https://npmjs.com/package/punycode) | MIT |
+| [`querystring-es3`](https://npmjs.com/package/querystring-es3) | MIT |
+| [`stream-browserify`](https://npmjs.com/package/stream-browserify) | MIT |
+| [`stream-http`](https://npmjs.com/package/stream-http) | MIT |
+| [`string_decoder`](https://npmjs.com/package/string_decoder) | MIT |
+| [`timers-browserify`](https://npmjs.com/package/timers-browserify) | MIT |
+| [`tty-browserify`](https://npmjs.com/package/tty-browserify) | MIT |
+| [`url`](https://npmjs.com/package/url) | MIT |
+| [`util`](https://npmjs.com/package/util) | MIT |
+| [`vm-browserify`](https://npmjs.com/package/vm-browserify) | MIT |
+
+## Additional credits
+
+- Bun's JS transpiler, CSS lexer, and Node.js module resolver source code is a port of [@evanw](https://github.com/evanw)’s [esbuild](https://github.com/evanw/esbuild) project.
+- Credit to [@kipply](https://github.com/kipply) for the name "Bun"!

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 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 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 those 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. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

package/NOTICE

@@ -0,0 +1,9 @@
+Velloo
+Copyright 2026 Prumo Works Ltd
+
+This product includes software developed at Prumo Works Ltd (https://velloo.design).
+
+This product also bundles and redistributes third-party open-source
+software. Those components remain under their own licenses; their copyright
+notices and license texts are collected in THIRD-PARTY-NOTICES.md, which
+accompanies this distribution.

package/README.md

@@ -1,3 +1,289 @@
-# velloo
+<div align="center">
 
-Reserved for the Velloo project. See [velloo.dev](https://velloo.dev).
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/velloo-lockup-dark.png">
+    <img src="./.github/assets/velloo-lockup.png" alt="Velloo" width="205">
+  </picture>
+</h1>
+
+**Design like a developer. Build like a designer.**
+
+Velloo is an open-source, local-first canvas for agent-driven design. It gives
+your coding agent a structured understanding of your app — its routes,
+components, theme, and conventions — so it can compose real screens, inspect the
+rendered result, and write the chosen design back into your app while you keep
+the taste and direction.
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-FFAB1F.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![npm](https://img.shields.io/npm/v/velloo.svg?color=FFAB1F)](https://www.npmjs.com/package/velloo)
+[![CI](https://github.com/velloo-design/velloo/actions/workflows/ci.yml/badge.svg)](https://github.com/velloo-design/velloo/actions/workflows/ci.yml)
+[![Discussions](https://img.shields.io/github/discussions/velloo-design/velloo?color=FFAB1F)](https://github.com/velloo-design/velloo/discussions)
+
+[Quickstart](#quickstart) · [Documentation](./docs) · [Contributing](./CONTRIBUTING.md) · [Discussions](https://github.com/velloo-design/velloo/discussions) · [velloo.design](https://velloo.design)
+
+</div>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/walkthrough-dark.gif">
+    <img src="./.github/assets/walkthrough.gif" alt="A coding agent designs an approval inbox in Velloo: three directions, a refinement, canvas and Velloo Cloud comments it resolves, and the implemented screen" width="100%">
+  </picture>
+</p>
+
+---
+
+## What is Velloo?
+
+Velloo adds a visual design loop to your coding agent. The agent works with your
+actual component system, explores and verifies directions on the canvas, and
+implements the direction you choose using your application's conventions.
+
+Designs are readable JSON that can live in your repo or outside it. The complete
+solo workflow is local and account-free; Velloo Cloud is optional when you want
+published boards, review links, and comments that return to the canvas.
+
+**No Figma seats. No paste-ready JSX you babysit. No translation tax.**
+
+> **Status:** early and moving fast. The design-folder format is versioned and
+> migrated by `velloo upgrade`, but expect rough edges and breaking changes
+> before 1.0. Bug reports and design feedback are very welcome.
+
+## Quickstart
+
+Install the CLI. The npm package pulls an exact official Bun platform binary
+with no install scripts — you don't install or manage Bun yourself:
+
+```bash
+npm install -g velloo          # or: pnpm add -g velloo
+```
+
+Prefer a standalone install (macOS and Linux)?
+
+```bash
+curl -fsSL https://get.velloo.design/install.sh | bash
+```
+
+Then, from inside your app:
+
+```bash
+cd ~/code/my-shadcn-app
+velloo init                    # interactive wizard
+velloo run velloo              # the design folder it just created
+```
+
+- **Canvas** → http://localhost:7300 (the next free port if that one is busy)
+- **MCP server** → your agent starts `velloo mcp` over stdio; `init` already
+  wrote that into its config. HTTP-only clients can run `velloo mcp --http`,
+  which prints the URL to use.
+
+Restart your agent so it picks up the new MCP config, then point it at a real
+screen:
+
+> "Use `velloo` to recreate the design for the billing page,
+> then show me three takes on the plan-comparison section."
+
+That's the loop. The agent builds on the canvas, screenshots its own work, and
+you react to pixels instead of to a diff.
+
+### What `init` does
+
+The wizard creates a design folder (default `velloo/`), detects your routes,
+component library, and theme, and connects supported coding agents through their
+native MCP configuration and guidance format. It never changes your app source;
+it only creates the design folder and agent configuration.
+
+### Ways to use Velloo
+
+- **Redesign an existing screen.** Recreate a route as a faithful baseline,
+  explore alternatives beside it, and compare the result with the running app.
+- **Start from scratch.** Choose your component library, then begin with the
+  sample board or a blank canvas for a new screen or product idea.
+- **Work from a live page.** Capture a public or authenticated page when the
+  useful starting point is a browser rather than a route in the current app.
+
+For better results, give the agent a concrete outcome and review bar: name the
+screen, ask for genuinely different directions, say which components or tokens
+must be preserved, and ask to see the canvas before application code changes.
+
+### Velloo Cloud and `velloo publish`
+
+Velloo Cloud is the optional collaboration layer; the local design remains the
+source of truth. When you want feedback from someone else, sign in and publish a
+board from the canvas or the CLI:
+
+```bash
+velloo login
+velloo publish velloo
+```
+
+Choose the boards, destination, and access level when prompted. Velloo uploads
+the material needed to render the review and prints a share link; comments on
+that link sync back to the local canvas for you or your agent to resolve. A later
+publish can update the same link and preserve its review context.
+
+Use `velloo publish list` to see existing publications and
+`velloo publish remove <share-url>` to take one down. Velloo Cloud is not
+required to design, export, or implement a screen.
+
+## Features
+
+- **Existing-screen redesign.** Start from a React route or a captured
+  authenticated page, recreate a faithful baseline, explore alternatives, and
+  compare against the running product at the same viewport.
+- **Real components, not approximations.** Components come from a
+  `ComponentProvider`, so the design folder stays pure data. For shadcn,
+  client-safe files from your app mount directly in the canvas; portal- and
+  state-heavy families are explicitly adapted; compile failures fall back per
+  component with diagnostics.
+- **Five React adapters.** shadcn + Tailwind, Material UI, Ant Design, Chakra
+  UI, and no-library React each render and emit through their own adapter.
+- **Visual verification.** The agent inspects rendered nodes, takes screenshots,
+  diffs against a live URL, and fixes what it sees instead of guessing from code.
+- **Board → Screen → Frame.** One design folder holds many boards; frames that
+  share a screen stay in sync, so a mobile and a desktop frame are one edit.
+- **A real MCP surface.** Discovery, focused tree mutations, themes, screenshots,
+  comparison, comments, and agent-consumed implementation IR — plus bundled
+  skills for brand, design systems, logos, and design-to-code.
+- **Optional collaboration.** Create a team, publish a board, share externally,
+  and pull review comments back into the local canvas.
+
+## Requirements
+
+| | |
+|---|---|
+| **OS** | macOS (arm64, x64) and Linux (arm64, x64; glibc and musl). Windows via WSL. |
+| **Your app** | React. shadcn + Tailwind, MUI, Ant Design, Chakra, and no-library folders are supported. |
+| **Screenshots** | Optional headless Chromium, one command away (below). |
+
+### Screenshots — the one optional extra
+
+A headless Chromium is used for exactly two things: your agent's `screenshot`
+tool (so it can *see* a design) and `velloo render <screen> --to=out.png`. The
+canvas, editing, `publish`, `emit`, and everything else work without it. Install
+it anytime (one-time, ~150 MB):
+
+```bash
+velloo browser install
+```
+
+If a screenshot ever fails, run exactly that command and retry.
+
+## CLI essentials
+
+A **design** is a folder with a `.design/config.json`, which holds its name. A
+repo-root **`velloo.json`** lists where the repo's designs are (several can
+coexist in a monorepo). Every design-taking command accepts a design name or a
+path, and resolves through `velloo.json` when you pass nothing. With several
+designs, a connected agent is told which one it is on and can switch between them.
+Commands that take something else as their argument, like `emit <screen>`, take
+the design as `--design`.
+
+| Command | What it does |
+|---|---|
+| `velloo init` | Create a design folder and wire up your agent |
+| `velloo run [design]` | Start the canvas + MCP daemon (`--port` to pick the canvas port) |
+| `velloo design list\|add\|remove\|move\|rename\|upgrade` | Manage the repo's designs |
+| `velloo emit` / `velloo render` | Implementation IR for your agent / a PNG of a screen |
+| `velloo publish [design]` | Publish a board for review (`publish list\|remove` manage what you've published) |
+| `velloo upgrade` | Update the install *and* migrate the design format (`--check` to preview) |
+
+`Ctrl-C` stops the server.
+
+**Keeping designs out of the app repo** is a first-class option — pick "Default
+out of repo" in the wizard, give a path outside the repo, or run
+`velloo init --external --name web`. The design is recorded
+only on your machine: nothing is written into the repo, the files live under
+`~/.velloo/designs/` (or where you chose) outside version control, and agents are
+wired through global configs. See
+[Local designs outside the repository](./docs/external-local-design-folders.md).
+
+**Choosing an MCP surface.** Velloo defaults to a compact progressive-disclosure
+surface: the agent sees `call_velloo`, `run_velloo_plan`, and `operation_schema`
+and pays for a native schema only when it needs one. Clients that do better with
+conventional function schemas can use `velloo mcp --surface full`. Both surfaces
+carry the whole operation catalogue. See [docs/mcp.md](./docs/mcp.md).
+
+## Local-first by default
+
+The local tool is free, complete, account-free, and telemetry-free.
+
+The CLI makes exactly one anonymous request outside the solo loop: at most daily,
+a detached check reads the public npm release version and caches it locally. It
+sends no project or account data, and `VELLOO_DISABLE_UPDATE_CHECK=1` turns it
+off. Everything else that touches the network is opt-in and gated behind an
+explicit `velloo login`:
+
+- `velloo login` / `velloo publish` — publish boards to a personal or team
+  workspace and create external review links
+- comment tools — read and resolve team and external-review feedback
+- `generate_asset` — hosted image/SVG generation, metered against your credits
+- `send_feedback` — agent-side product feedback, only when enabled in the folder
+  config
+
+You choose when — and whether — to use any of them.
+
+## Documentation
+
+| | |
+|---|---|
+| [docs/architecture.md](./docs/architecture.md) | Design-folder format, providers, renderer, codegen, canvas daemon |
+| [docs/mcp.md](./docs/mcp.md) | The MCP tool surface agents talk to |
+| [docs/providers.md](./docs/providers.md) | Adding a framework adapter |
+| [docs/css-class-channel.md](./docs/css-class-channel.md) | How styling is routed per framework |
+| [docs/external-local-design-folders.md](./docs/external-local-design-folders.md) | Local designs outside the repo: storage, agents, relocation, binding |
+
+## Contributing
+
+Contributions are welcome — bug reports, adapters, docs, and design feedback
+alike. [`CONTRIBUTING.md`](./CONTRIBUTING.md) covers setup and the checks we
+expect to be green; [`CLAUDE.md`](./CLAUDE.md) explains the repo's architecture
+invariants before you change anything load-bearing.
+
+The short version:
+
+```bash
+bun install                                 # also builds the snapshot manifest
+bun run --cwd packages/canvas build         # build the canvas SPA
+bun run velloo init /tmp/velloo-smoke
+bun run velloo run /tmp/velloo-smoke        # canvas on :7300
+bun run verify                              # typecheck + lint + knip + tests
+```
+
+Good first issues are labelled
+[`good first issue`](https://github.com/velloo-design/velloo/labels/good%20first%20issue).
+
+### Repo layout
+
+Velloo is a Bun-workspaces monorepo with one-way dependencies:
+
+| Package | Responsibility |
+|---|---|
+| `packages/schema` | Zod schemas + TS types for the on-disk design-folder format |
+| `packages/protocol` | The wire contract: mutation arguments, typed errors, watch events |
+| `packages/provider` | The `ComponentProvider` / `FrameworkAdapter` interface |
+| `packages/provider-*` | shadcn, MUI, Ant Design, Chakra, and no-library adapters |
+| `packages/shadcn-snapshot` | Pinned canvas-safe shadcn fallback, embedded in the binary |
+| `packages/renderer` | Design JSON → HTML (and PNG via Playwright) |
+| `packages/codegen` | Agent-consumed IR + theme emitters |
+| `packages/server` | HTTP + MCP + mutations + theme + watcher |
+| `packages/canvas` | Vite/React canvas UI |
+| `packages/cli` | The `velloo` binary |
+
+## Community and support
+
+- **Questions, ideas, show-and-tell** →
+  [Discussions](https://github.com/velloo-design/velloo/discussions)
+- **Bugs and feature requests** →
+  [open an issue](https://github.com/velloo-design/velloo/issues/new/choose)
+- **Security issues** → [`SECURITY.md`](./SECURITY.md) — please don't file a
+  public issue
+- **Ground rules** → [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
+
+## License
+
+Velloo is open source under the [Apache License 2.0](./LICENSE).
+
+The **Velloo** name and the interlinked-frames mark are trademarks and are not
+covered by the code license — fork the code freely, but don't ship a derivative
+under the Velloo name or logo. See [`TRADEMARK.md`](./TRADEMARK.md).