@zodiaceco/create 2.7.0 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zodiaceco/create",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Start a Zodiac constellation project: npm create @zodiaceco",
   "author": "Zodiac Labs GmbH",
   "license": "LGPL-3.0-only",

package/templates/constellation/CLAUDE.md

@@ -1,28 +1,12 @@
-# Zodiac Constellation — agent notes
-
-This repo is a **Zodiac constellation**: a TypeScript description of an org's smart-account graph (Safes, mods, users, permissions). `npm run push` sends the spec to Zodiac, which diffs it against onchain state and gives a UI to review + sign the transactions.
-
-User-facing docs are in `README.md` — read it before suggesting edits to `constellation/`.
-
-## Project map
-
-- `constellation/index.ts` — entrypoint. **Only exported values get pushed.**
-- `constellation/roles/<role>/` — `members.ts` (addresses) + `permissions.ts`
-  (a list of entries: `custom`, `defikit`, `swap`, `transfer` from
-  `@zodiaceco/sdk/actions`, or a bare `allow` kit permission).
-- `constellation/allowances/` — reusable Roles allowance objects (key, refill, period, ...).
-  A permission draws on one by naming its key: `c.withinAllowance("usdc_payouts")`.
-- `zodiac.config.ts` — contracts the `allow` kit should know about.
-- `.zodiac/` — generated codegen; **never edit by hand**. Re-run `npm run pull` (or `pull-org` / `pull-contracts`) to refresh.
-
-## Conventions
-
-- Entries **describe, they never compile**. `defikit` stores a protocol, verb
-  and parameters; `swap` stores its token lists. The permissions are built when
-  the constellation is deployed, so a stored revision never carries a copy of
-  what a preset meant on the day it was written.
-
-- Import `constellation`, `allow`, `c` and the `Members` / `Permissions` types from `@zodiaceco/sdk`, the entries from `@zodiaceco/sdk/actions`.
-- After editing `zodiac.config.ts` (contracts) or anything that changes referenced accounts/users, run `npm run pull` so the generated types match.
-- Any package manager works: run the scripts with `npm run`, `pnpm`, `yarn` or `bun run`. The `zodiac` CLI loads `.env` itself.
-- `npx zodiac push --dry-run` prints what would be pushed, without pulling or an API key: use it to check an edit.
+# Agent notes
+
+A Zodiac constellation: TypeScript describing an org's Safes, Roles mods and permissions. `README.md` has the full API.
+
+- Only values exported from `constellation/index.ts` are pushed.
+- A new role needs its folder under `constellation/roles/`, an export in `constellation/roles/index.ts`, and an entry in the Roles mod's `roles`.
+- `c.withinAllowance("<key>")` only works if that allowance is in the Roles mod's `allowances`.
+- `allow.<chain>.<contract>` only knows contracts listed in `zodiac.config.ts`. After changing them, run `npm run pull-contracts`.
+- Never edit `.zodiac/` or `abis/`: they're generated. Run `npm run pull` to refresh them.
+- Import `constellation`, `allow`, `c` and the types from `@zodiaceco/sdk`; `custom`, `defikit`, `swap` and `transfer` from `@zodiaceco/sdk/actions`.
+- Check an edit with `npx tsc --noEmit` and `npx zodiac push --dry-run`; neither needs an API key.
+- Don't run `npm run push` unless asked: it sends the constellation to the org's Zodiac workspace.

package/templates/constellation/README.md

@@ -251,6 +251,34 @@ allow.eth.susds["deposit(uint256,address)"](
 );
 ```
 
+### Showing Safes and roles in the Zodiac app
+
+A constellation deploys everything it describes, but the Zodiac app only lists what you mark for the rest of your org.
+
+**Vaults.** Add `vault: true` to a Safe to list it under **Vaults**. It's named by its label, the key in `eth.safe["Treasury"]`:
+
+```ts
+export const treasury = eth.safe["Treasury"]({
+  nonce: 0n,
+  threshold: 1,
+  owners: ["0x…"],
+  modules: [eth.roles["Treasury Roles"]],
+  vault: true,
+});
+```
+
+**Policies.** Export `policy` from a role's folder to list the role under **Policies**, so everyone in your org can see what it permits. The value is the policy's name; a `description` is optional:
+
+```ts
+// constellation/roles/treasury_ops/index.ts
+export { default as members } from "./members";
+export { default as permissions } from "./permissions";
+export const policy = "Treasury Ops";
+export const description = "Day-to-day treasury operations";
+```
+
+Neither reaches the chain. The policy's identity is the role key (`treasury_ops`), not its name, so renaming it changes nothing onchain. Every Roles mod that has a role with the same key carries the same policy: each of them has to give it the same name, description, members and permissions, and no two of them may act for the same Safe.
+
 ## Commands
 
 | Command                  | What it does                                                                                                                    |