@montytools/cli 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montytools/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",

package/skills/monty-operate/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: monty-operate
+description: Operate a team's Monty workspace apps from the terminal — read and write a Live app's records with `monty data`. Use whenever the task is to put data INTO an existing Monty app or read data from one: add leads to a CRM, import scraped or external data, update or clean up records, check what an app currently stores, or automate recurring work against apps on usemonty.dev. Building or changing an app itself is monty-build, not this.
+---
+
+# Operating Monty apps
+
+A Monty workspace runs internal apps (CRMs, trackers, dashboards) whose data
+lives on the platform. `monty data` is how you — the operating agent — read
+and write that data directly from the terminal: no browser session, no dev
+server. You do the work (browse, scrape, decide, transform); the app is
+where the results land, and open app tabs update live as you write.
+
+Two data channels per app: **Live** (the team's real records — the default
+target) and the **Studio sandbox** (`--studio` — development data, never
+seen by the team). Writing to Live is normal operating work; that is what
+this command is for.
+
+## The loop
+
+1. **Find the app.** `monty apps` lists local apps; run inside the app
+   folder (`cd "$(monty select <slug>)"`) or pass `--app <slug>` to every
+   command.
+2. **Learn the shape — never guess.** `monty data schema` prints every
+   table; `monty data schema <table>` one table. (Schema compiles from the
+   local source — if the app isn't on this machine, `monty pull <slug>`
+   first.)
+3. **See what's there.** `monty data list <table> --limit 20` before
+   writing: learn the field conventions from real rows and avoid duplicating
+   what exists.
+4. **Write.** Prefer `upsert` with a `--key` for anything imported or
+   scraped; `insert` only for rows that are genuinely new by construction.
+5. **Verify.** `list`/`get` the rows you touched; report counts (added,
+   updated, skipped) with specifics.
+
+## Rules
+
+1. **Imports are idempotent.** Any repeatable job (scraping, syncing,
+   importing) writes with
+   `monty data upsert <table> --key <identityField> --data '[…]'` — the key
+   names the field(s) that identify a row (a URL, an email, an external id),
+   values come from each row, and re-running never duplicates.
+2. **Schema first, rows second.** Field names come from
+   `monty data schema`, exact spelling. The server stores what you send —
+   a misspelled field is silently a new field, not an error.
+3. **Live is the default and that's correct** — operating work targets the
+   team's real data. Use `--studio` only when explicitly rehearsing.
+   Destructive verbs (`remove`, bulk `update`) on Live deserve a
+   confirmation with the user unless they clearly asked for the cleanup.
+4. **Batch with arrays.** `--data` accepts a single object or an array;
+   arrays write row by row and return all ids in order.
+5. **Paginate honestly.** `list` returns `"cursor": null` when complete; a
+   non-null cursor means more rows exist — repeat with `--cursor <c>`
+   before claiming totals.
+6. **Errors are instructions.** Every failure prints
+   `[MontyError CODE] Fix: …` — do what the Fix says. `NOT_LOGGED_IN` means
+   run `monty login` (once per machine); `NOT_FOUND` on an id means it came
+   from the wrong table or a stale listing — re-`list`, never retry blind.
+7. **Rows come back flattened**: your fields at the top level plus system
+   fields `_id`, `_creationTime`, `updatedAt`, `createdBy`. System fields
+   are read-only — never send them in `--data`.
+
+## Command reference
+
+| command | purpose |
+|---|---|
+| `monty data schema [table]` | table shapes from the app's config — read this before any write |
+| `monty data list <table> [--filter '{"k":"v"}'] [--order asc\|desc] [--limit N] [--cursor C]` | newest-first rows; filter is exact-match on fields |
+| `monty data get <table> <id>` | one row (null if the id isn't in this table) |
+| `monty data insert <table> --data '<json\|[json,…]>'` | create rows |
+| `monty data upsert <table> --key <field[,field]> --data '<json\|[json,…]>'` | find-or-create matched on the key fields — the idempotent write |
+| `monty data update <table> <id> --data '<json>' [--unset a,b]` | shallow-merge onto one row; `--unset` deletes fields |
+| `monty data remove <table> <id>` | delete one row |
+
+All verbs take `--app <slug>` and `--studio`. Output is one JSON document on
+stdout.
+
+## Example: import scraped leads into a CRM app
+
+```sh
+monty data schema leads --app crm                # shape: name, company, title, linkedinUrl, status…
+monty data list leads --app crm --limit 50       # what's already in the pipeline
+# …browse/scrape/decide, then land the batch idempotently:
+monty data upsert leads --app crm --key linkedinUrl --data '[
+  {"name":"Dana Reeve","company":"Acme","title":"VP Ops","linkedinUrl":"https://linkedin.com/in/dana-r","status":"new"},
+  {"name":"Sam Ortiz","company":"Initech","title":"Head of RevOps","linkedinUrl":"https://linkedin.com/in/sam-o","status":"new"}
+]'
+monty data list leads --app crm --filter '{"status":"new"}'   # verify, then report counts
+```