gigarag-cursor 0.1.2 → 0.3.0

package/skills/gigasync/SKILL.md

@@ -19,7 +19,7 @@ The work is split on purpose. The `gigarag` command does the mechanical half: it
 
 ## 1. Scan
 
-Run `gigarag scan <path>` with the path you were given, or the current directory. It prints a JSON manifest. Read these fields:
+Run `gigarag scan <path>` with the path you were given, or the current directory. If it exits nonzero and prints a line about an untrusted workspace instead of JSON, stop immediately: do not run `gigarag use` yourself, and do not fall back to indexing without a manifest. Report the line it printed and end there. Otherwise it prints a JSON manifest. Read these fields:
 
 - `repo.slug` is the bucket. `repo.root` is the repository root.
 - `files` lists new and changed files, each with `path`, `hash`, `status`, `lines`, `language`, `nodeIds` (memos already made from it) and sometimes `chunks` (line ranges, when the file is too long for one memo).
@@ -30,7 +30,7 @@ If `files` and `removed` are both empty, report "Up to date" and stop.
 
 ## 2. Find or create the bucket and threads
 
-Call `list_buckets` with `q` set to the slug. Use the bucket whose slug matches exactly, or `create_bucket` with that slug, the repository name as the title, and a one line description. Slugs are lowercase letters, digits and hyphens, at most 64 characters.
+Call `list_buckets` with `q` set to the slug and use the bucket whose slug matches exactly. If `repo.bound` is true in the manifest, the bucket was chosen in `.gigarag.json`: never call `create_bucket`. If it is not in the list, stop and tell the person that the bucket named in .gigarag.json is not reachable with their access, and that `gigarag use <workspace> --bucket <slug>` links another. Otherwise, when no bucket matches, `create_bucket` with that slug, the repository name as the title, and a one line description. Slugs are lowercase letters, digits and hyphens, at most 64 characters.
 
 Group memos into threads by the top level area of the repository: `src`, `docs`, `tests`, `config`. Look them up with `list_threads` for the bucket and create the missing ones. Keep the number of threads under about ten.
 
@@ -44,13 +44,16 @@ Work in batches of about ten files. For each file:
 - The title says what the module is, for example "Session token refresh". The summary is one or two sentences. `node_type` is `code` for source, `doc` for markdown and prose, `config` for configuration. The slug comes from the path, for example `src-auth-session-ts`. Set `actor` to `agent:gigarag-indexer`.
 - A body holds at most 10,000 characters. For a long file with `chunks`, write one memo per chunk and a short parent memo that links to them.
 - If `nodeIds` is not empty, the file was indexed before. Call `update_node` on that node instead of creating a second one, and keep the `[Title](N:12)` links already in its text unless the thing they point at is gone.
+- A memo whose source changed carries `stale: true`. Rewriting its content with `update_node` clears the mark. If you read the file and the memo is still right, send its body back unchanged, which clears the mark too.
 - Where this memo depends on another module, link it in the text as `[Module name](N:12)`. Get the ref from `find_nodes` with part of the title, or from a memo you have already written this run. Never write a UUID as a link target. After each write, look at `unresolved_links` in the reply and fix or remove any ref that did not resolve.
 
 ## 4. Record progress after every batch
 
-After each batch, pipe the result to `gigarag record` so a later run updates in place and an interrupted run can resume. Send JSON on stdin:
+After each batch, pipe the result to `gigarag record` so a later run updates in place and an interrupted run can resume. Send JSON on stdin with a heredoc, so the command line stays `gigarag record` and nothing else:
 
+gigarag record <<'JSON'
 {"repo":"<slug>","files":[{"path":"src/auth.ts","hash":"<hash from the manifest>","nodes":[{"id":"<node id>","ref":"N:12","title":"Session token refresh","type":"code","tokens":600}]}]}
+JSON
 
 `tokens` is your rough estimate of what fetching the memo costs, at about four characters a token. Do this per batch, not once at the end.