zinkee 0.1.12 → 0.1.17

package/AGENTS.md

@@ -50,3 +50,45 @@ Use this order when reasoning about behavior:
 ## Testing
 
 Prefer focused command tests and parser/client unit tests.
+
+> **Unit tests use `fetchMock` and never hit the real API.** When changing the
+> shape of a payload (enum values, property names, structure), unit tests will
+> still pass even if the real API would reject the request with `400`. For
+> shape-sensitive changes — especially edits to strings in `src/utils/examples.ts`
+> — also run the resulting command against a real workspace and confirm the API
+> accepts it.
+
+## Contributing
+
+### Branches
+
+- `feature/eng-<ticket>-<slug>` for Linear-tracked work
+- `fix/<slug>` / `chore/<slug>` / `docs/<slug>` for untracked work
+- Never push to `main` directly; always open a PR
+
+### Commits
+
+- Conventional Commits format: `<type>(<scope>): <subject>` (e.g.
+  `fix(displays): correct chart-type values in widget examples`)
+- Subject in imperative mood, under ~72 chars, no trailing period
+- Body explains the *why*, not the *what* — the diff already shows what changed
+- Stage files explicitly (`git add <path>`); never `git add -A`
+- Don't add `Co-Authored-By:` trailers; existing history doesn't use them
+
+### Before committing
+
+1. `npm run typecheck` — must pass
+2. `npm test` — must pass
+3. For changes that affect runtime behaviour or `--example` output, also
+   exercise the affected commands against a live workspace (see Testing note
+   above).
+
+### Versioning
+
+- Versioning is patch-only today (`0.1.x`). Bump the patch number unless the
+  team decides to move to a different scheme.
+- Every PR that ships user-visible changes (new commands, fixed examples,
+  behaviour changes) bumps `package.json` version in the same PR — not in a
+  separate "release" PR.
+- Before bumping, fetch `origin/main` to make sure the version you pick isn't
+  already taken by another PR that merged ahead of yours.

package/README.md

@@ -273,10 +273,17 @@ zinkee records update projects <record-uuid> --set status=2
 
 # Delete
 zinkee records delete projects <record-uuid>
+
+# Clear all records from a schema (destructive — irreversible)
+zinkee records clear projects
 ```
 
 Option values are written as numbers (`--set status=1`) but returned as strings (`"1"`). Number values are stored and returned as strings.
 
+`records clear` removes every record from the schema's table. Heritage rules
+(`CASCADE` / `SET NULL`) propagate to child schemas asynchronously through the
+CDC pipeline, so related tables converge eventually. Blocked by `--read-only`.
+
 ---
 
 ## Files