gigarag-copilot 0.1.0

package/cli/state.js

@@ -0,0 +1,210 @@
+import { createRequire } from 'node:module';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDir } from './paths.js';
+/**
+ * node:sqlite prints an ExperimentalWarning the first time it loads. A hook's
+ * stderr lands in the middle of somebody's terminal session, so the warning is
+ * swallowed for the one require and the original handler put back.
+ */
+function loadSqlite() {
+    const original = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const type = typeof rest[0] === 'string' ? rest[0] : rest[0]?.type;
+        if (type === 'ExperimentalWarning' || (warning instanceof Error && warning.name === 'ExperimentalWarning'))
+            return;
+        return original.call(process, warning, ...rest);
+    });
+    try {
+        return createRequire(import.meta.url)('node:sqlite');
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS repos (
+  slug TEXT PRIMARY KEY, root TEXT NOT NULL, indexed_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS files (
+  repo TEXT NOT NULL, path TEXT NOT NULL, hash TEXT NOT NULL,
+  dirty INTEGER NOT NULL DEFAULT 0, indexed_at INTEGER,
+  PRIMARY KEY (repo, path)
+);
+CREATE TABLE IF NOT EXISTS links (
+  repo TEXT NOT NULL, path TEXT NOT NULL, node_id TEXT NOT NULL,
+  PRIMARY KEY (repo, path, node_id)
+);
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id TEXT PRIMARY KEY, ref TEXT, title TEXT NOT NULL, type TEXT,
+  tokens INTEGER, touched_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS nodes_touched ON nodes (touched_at DESC);
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+`;
+export class State {
+    db;
+    cache = new Map();
+    constructor(path = join(stateDir(), 'state.db')) {
+        // Private, like the key file beside it: memo titles and repository paths are not for other users of the machine.
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const { DatabaseSync } = loadSqlite();
+        this.db = new DatabaseSync(path);
+        // Several Claude Code sessions write to this file at once, each from its own hook process.
+        this.db.exec('PRAGMA busy_timeout = 2000; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;');
+        this.db.exec(SCHEMA);
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            /* Windows has no chmod that means anything */
+        }
+    }
+    stmt(sql) {
+        let s = this.cache.get(sql);
+        if (!s) {
+            s = this.db.prepare(sql);
+            this.cache.set(sql, s);
+        }
+        return s;
+    }
+    close() {
+        this.db.close();
+    }
+    transaction(fn) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const out = fn();
+            this.db.exec('COMMIT');
+            return out;
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    // --- meta ---------------------------------------------------------------
+    getMeta(key) {
+        return this.stmt('SELECT value FROM meta WHERE key = ?').get(key)?.value;
+    }
+    setMeta(key, value) {
+        this.stmt('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, value);
+    }
+    /**
+     * Takes a lock that lapses after `ttlMs`, in one transaction, so two workers starting together
+     * cannot both see it free. Returns whether this caller now holds it.
+     */
+    tryAcquire(key, ttlMs, now = Date.now()) {
+        return this.transaction(() => {
+            if (now - Number(this.getMeta(key) ?? 0) < ttlMs)
+                return false;
+            this.setMeta(key, String(now));
+            return true;
+        });
+    }
+    // --- repos and files ------------------------------------------------------
+    upsertRepo(slug, root, indexedAt) {
+        this.stmt(`INSERT INTO repos (slug, root, indexed_at) VALUES (?, ?, ?)
+       ON CONFLICT(slug) DO UPDATE SET root = excluded.root, indexed_at = COALESCE(excluded.indexed_at, indexed_at)`).run(slug, root, indexedAt ?? null);
+    }
+    listRepos() {
+        return this.stmt('SELECT slug, root, indexed_at FROM repos ORDER BY slug').all();
+    }
+    hasRepo(slug) {
+        return this.stmt('SELECT 1 AS x FROM repos WHERE slug = ?').get(slug) !== undefined;
+    }
+    repoBySlug(slug) {
+        return this.stmt('SELECT slug, root, indexed_at FROM repos WHERE slug = ?').get(slug);
+    }
+    files(repo) {
+        const rows = this.stmt('SELECT path, hash, dirty FROM files WHERE repo = ?').all(repo);
+        return new Map(rows.map(r => [r.path, r]));
+    }
+    nodesOf(repo, path) {
+        return this.stmt('SELECT node_id FROM links WHERE repo = ? AND path = ?').all(repo, path).map(r => r.node_id);
+    }
+    /** Nodes that only these paths point at, so deleting the files means deleting them. */
+    orphansIfRemoved(repo, paths) {
+        const removing = new Set(paths);
+        const out = new Map();
+        for (const path of paths) {
+            const orphaned = [];
+            for (const id of this.nodesOf(repo, path)) {
+                const holders = this.stmt('SELECT repo, path FROM links WHERE node_id = ?').all(id);
+                const remaining = holders.filter(h => !(h.repo === repo && removing.has(h.path)));
+                if (remaining.length === 0)
+                    orphaned.push(id);
+            }
+            out.set(path, orphaned);
+        }
+        return out;
+    }
+    /** Records that `path` was indexed at `hash` and now lives in `nodeIds`. */
+    recordFile(repo, path, hash, nodeIds, now = Date.now()) {
+        this.transaction(() => {
+            this.stmt(`INSERT INTO files (repo, path, hash, dirty, indexed_at) VALUES (?, ?, ?, 0, ?)
+         ON CONFLICT(repo, path) DO UPDATE SET hash = excluded.hash, dirty = 0, indexed_at = excluded.indexed_at`).run(repo, path, hash, now);
+            for (const id of nodeIds) {
+                this.stmt('INSERT OR IGNORE INTO links (repo, path, node_id) VALUES (?, ?, ?)').run(repo, path, id);
+            }
+        });
+    }
+    forgetFile(repo, path) {
+        this.transaction(() => {
+            this.stmt('DELETE FROM files WHERE repo = ? AND path = ?').run(repo, path);
+            this.stmt('DELETE FROM links WHERE repo = ? AND path = ?').run(repo, path);
+        });
+    }
+    markDirty(repo, path) {
+        const res = this.stmt('UPDATE files SET dirty = 1 WHERE repo = ? AND path = ?').run(repo, path);
+        return Number(res.changes) > 0;
+    }
+    /** A file saved without changing has nothing to re-index, so its flag goes. */
+    clearDirty(repo, path) {
+        this.stmt('UPDATE files SET dirty = 0 WHERE repo = ? AND path = ? AND dirty = 1').run(repo, path);
+    }
+    dirtyCount(repo) {
+        return this.stmt('SELECT COUNT(*) AS n FROM files WHERE repo = ? AND dirty = 1').get(repo).n;
+    }
+    dirtyFiles(repo) {
+        return this.stmt('SELECT path FROM files WHERE repo = ? AND dirty = 1 ORDER BY path').all(repo).map(r => r.path);
+    }
+    // --- the session index ------------------------------------------------------
+    upsertNode(row) {
+        this.stmt(`INSERT INTO nodes (node_id, ref, title, type, tokens, touched_at) VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         ref = COALESCE(excluded.ref, ref), title = excluded.title, type = COALESCE(excluded.type, type),
+         tokens = COALESCE(excluded.tokens, tokens), touched_at = excluded.touched_at`).run(row.node_id, row.ref ?? null, row.title, row.type ?? null, row.tokens ?? null, row.touched_at ?? Date.now());
+    }
+    deleteNode(nodeId) {
+        this.transaction(() => {
+            this.stmt('DELETE FROM nodes WHERE node_id = ?').run(nodeId);
+            this.stmt('DELETE FROM links WHERE node_id = ?').run(nodeId);
+        });
+    }
+    /** Replaces the synced set: rows not in `keep` are dropped, so deletions elsewhere disappear here. */
+    replaceNodes(rows) {
+        this.transaction(() => {
+            const known = new Map(this.stmt('SELECT node_id, tokens FROM nodes').all().map(r => [r.node_id, r.tokens]));
+            this.db.exec('DELETE FROM nodes');
+            for (const row of rows) {
+                this.stmt('INSERT INTO nodes (node_id, ref, title, type, tokens, touched_at) VALUES (?, ?, ?, ?, ?, ?)').run(row.node_id, row.ref, row.title, row.type, row.tokens ?? known.get(row.node_id) ?? null, row.touched_at);
+            }
+        });
+    }
+    recentNodes(limit) {
+        return this.stmt('SELECT node_id, ref, title, type, tokens, touched_at FROM nodes ORDER BY touched_at DESC LIMIT ?').all(limit);
+    }
+    nodeCount() {
+        return this.stmt('SELECT COUNT(*) AS n FROM nodes').get().n;
+    }
+}
+/** Opens the state, or returns undefined when it cannot be opened, so a hook never fails a session. */
+export function tryOpenState(path) {
+    try {
+        return new State(path);
+    }
+    catch {
+        return undefined;
+    }
+}

package/cli/ui.js

@@ -0,0 +1,66 @@
+import { stdin, stdout } from 'node:process';
+export const out = (line = '') => stdout.write(`${line}\n`);
+export const err = (line = '') => process.stderr.write(`${line}\n`);
+/** Pads columns so a list reads as a table without box drawing. */
+export function table(rows, gap = 2) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, cell.length)));
+    return rows.map(row => row
+        .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i] + gap)))
+        .join('')
+        .trimEnd());
+}
+/** Reads a line from the terminal without echoing it, for a key that should not land in scrollback. */
+export function promptHidden(question) {
+    return new Promise((resolve, reject) => {
+        if (!stdin.isTTY) {
+            reject(new Error('No terminal to prompt on.'));
+            return;
+        }
+        stdout.write(question);
+        let value = '';
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        const done = (fn) => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.off('data', onData);
+            stdout.write('\n');
+            fn();
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n')
+                    return done(() => resolve(value));
+                if (ch === '\u0003')
+                    return done(() => reject(new Error('Cancelled.')));
+                if (ch === '\u007f' || ch === '\b')
+                    value = value.slice(0, -1);
+                else if (ch >= ' ')
+                    value += ch;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+/** First line of piped input, for `echo $KEY | gigarag login`. */
+export async function readStdinLine() {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8').split(/\r?\n/)[0]?.trim() ?? '';
+}
+export async function readStdinAll() {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}

package/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gigarag": {
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/scripts/run.mjs", "mcp"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "gigarag-copilot",
+  "version": "0.1.0",
+  "description": "The GigaRAG plugin for VS Code and Copilot CLI. Skills and an MCP server that carry the gigarag CLI inside them.",
+  "license": "UNLICENSED",
+  "files": [
+    "plugin.json",
+    "skills",
+    "scripts",
+    "cli",
+    "mcp.json",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gigarag/gigarag-cli.git",
+    "directory": "plugins/copilot"
+  },
+  "homepage": "https://gigarag.com"
+}

package/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "gigarag",
+  "description": "Your GigaRAG knowledge base inside VS Code and Copilot CLI: index a codebase, save decisions, recall them later.",
+  "version": "0.1.0",
+  "author": { "name": "GigaRAG", "url": "https://gigarag.com" },
+  "homepage": "https://gigarag.com/connect/copilot-plugins",
+  "license": "UNLICENSED",
+  "keywords": ["memory", "rag", "knowledge-base", "mcp"]
+}

package/scripts/run.mjs

@@ -0,0 +1,64 @@
+// Finds the gigarag CLI and runs it, so every hook, command and MCP entry in this
+// plugin calls one thing. Lookup order:
+//   1. GIGARAG_CLI, a path to bin.js, for development
+//   2. ../cli/bin.js, the build vendored into this package at release time
+//   3. a gigarag on PATH, such as npm i -g gigarag or the standalone installer
+//   4. npx, which downloads the version this plugin was released with
+// The CLI is vendored because Claude Code does not run install scripts and npm never
+// publishes a lockfile, so a declared dependency would not be there on first run.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const here = dirname(fileURLToPath(import.meta.url));
+const isHook = args[0] === 'hook';
+const windows = process.platform === 'win32';
+
+const local = [process.env.GIGARAG_CLI, join(here, '..', 'cli', 'bin.js')].find(p => p && existsSync(p));
+
+/** The version this plugin shipped with, so npx runs the CLI it was tested against and not whatever is newest. */
+const pinned = () => {
+  try {
+    const { version } = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    return /^\d+\.\d+\.\d+(-[\w.]+)?$/.test(version) ? `gigarag@${version}` : 'gigarag';
+  } catch {
+    return 'gigarag';
+  }
+};
+
+/** True when the command exists. A probe, because a shell reports a missing command as an ordinary exit code. */
+const exists = (cmd, probe) => {
+  const r = spawnSync(cmd, probe, { stdio: 'ignore', shell: windows });
+  return !r.error && r.status === 0;
+};
+
+/**
+ * On Windows gigarag and npx are .cmd scripts, which Node will only start through cmd.exe. What a
+ * user typed after a slash command ends up in these arguments, so anything cmd.exe would read as
+ * syntax is refused rather than passed on.
+ */
+const unsafeForCmd = list => windows && list.some(a => /[&|<>^%"\r\n`]/.test(a));
+
+if (local) {
+  // In this process: no second Node start, which matters inside a 100ms hook budget.
+  await import(pathToFileURL(local).href);
+} else {
+  const attempts = [
+    ['gigarag', ['--version'], 'gigarag', args],
+    ['npx', ['--version'], 'npx', ['-y', pinned(), ...args]],
+  ];
+  const found = attempts.find(([probeCmd, probeArgs]) => exists(probeCmd, probeArgs));
+  if (found && unsafeForCmd(found[3])) {
+    if (!isHook) process.stderr.write('gigarag: an argument holds a character that cmd.exe would treat as syntax, so nothing was run.\n');
+    process.exitCode = isHook ? 0 : 1;
+  } else if (found) {
+    const r = spawnSync(found[2], found[3], { stdio: 'inherit', shell: windows });
+    // A hook must never break the session it runs in.
+    process.exitCode = isHook ? 0 : (r.status ?? 1);
+  } else {
+    if (!isHook) process.stderr.write('gigarag is not installed. Run: npm install -g gigarag\n');
+    process.exitCode = isHook ? 0 : 1;
+  }
+}

package/skills/gigadocs/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: gigadocs
+description: Ingest external documentation into GigaRAG so it can be searched later
+---
+
+Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.
+
+Ingest the documentation at the text the user typed after the skill name into GigaRAG.
+
+If that is empty or is not a URL, ask me for one and stop.
+
+The bucket is named for the site: the hostname with dots turned into hyphens and any leading `www` dropped, so docs.stripe.com becomes `docs-stripe-com`. Find it with `list_buckets`, and create it if it is missing, with the site name as the title.
+
+Then:
+1. Fetch the page. Follow links that stay on the same host and sit under the same path prefix as the starting URL, up to two levels deep and at most 30 pages. Skip anchors, downloads, login pages and anything that repeats a page you already have. Say so if you hit the 30 page limit.
+2. For each page, first call `search_nodes` for its URL. If a memo already carries that URL, update it in place with `update_node` instead of creating a duplicate, so running this twice does not double the bucket.
+3. Otherwise `create_node`. The title is the page's own title. The summary is one or two sentences on what the page covers. The body opens with the line `Source: <url>, retrieved <today's date>`, then the page's content as clean markdown: keep headings, code blocks and tables, drop navigation, footers, cookie banners and repeated menus.
+4. A memo body holds at most 10,000 characters. For a longer page, split at a heading into several memos titled "Page title, part 2" and so on, and link each part to the next in its text as `[Page title, part 2](N:12)`.
+5. Set `node_type` to `doc` and `actor` to `agent:claude-code`.
+
+When you finish, tell me the bucket, how many pages you created and updated, how many you skipped and why, and one example query I could try with `/gigarecall`.

package/skills/gigaindex/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gigaindex
+description: Index a codebase into GigaRAG, one bucket per repository
+---
+
+Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.
+
+This needs a shell tool, because it runs the `gigarag` command. If you have no way to run shell commands, say so in one sentence and stop. Do not guess at what the repository contains.
+
+Index a codebase into GigaRAG. The path to index is: "the text the user typed after the skill name". If that is empty, use the current directory.
+
+Do the work yourself, in this conversation, following the procedure below. When you finish, tell the user in five lines or fewer: the bucket, how many memos you created, updated and deleted, anything you could not index and why, and whether the index is up to date. Do not paste the file list.
+
+## Procedure
+
+The work is split on purpose. The `gigarag` command does the mechanical half: it walks the tree, respects gitignore, hashes contents, plans chunk boundaries and works out what changed. You do the judgement half: what a module is for, what is worth summarising, and what links to what. Never walk the filesystem yourself with ls or find. The manifest names every file you need.
+
+## 1. Scan
+
+Run `gigarag scan <path>` with the path you were given, or the current directory. 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).
+- `removed` lists files that are gone, each with `nodeIds` and `deleteNodeIds`.
+- `truncated: true` means the walk hit its limit. Tell the user in your report and carry on with what you have.
+
+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.
+
+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.
+
+## 3. Write the memos
+
+Work in batches of about ten files. For each file:
+
+- Read it with the Read tool. When it has `chunks`, read one range at a time using `offset` and `limit`.
+- Write a memo that explains the file to somebody who has not read it. Cover what it is for, its public surface (exported names and signatures, not their bodies), how it connects to the rest of the system, and any non-obvious constraint. Aim for 500 to 2,500 characters. Do not paste the source. A memo that only restates the code is worse than none.
+- Very small files that only make sense together, such as a folder of three tiny helpers, may share one memo. Give each of those files the same node when you record them.
+- 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.
+- 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:
+
+{"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}]}]}
+
+`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.
+
+## 5. Remove what is gone
+
+For each entry in `removed`, call `delete_node` for every id in its `deleteNodeIds`. For memos that other files still feed, use `update_node` to take the removed file out of the text. Then record it:
+
+{"repo":"<slug>","removed":[{"path":"src/old.ts","deletedNodeIds":["<node id>"]}]}
+
+Without this half the index only ever grows and drifts away from the repository while still looking correct.
+
+## Rate limits
+
+If a tool answers that you are rate limited, wait and continue. Do not start over. Files you have already recorded are skipped by the next `gigarag scan`, so an interrupted index resumes where it stopped.
+
+## Report
+
+End with this, and nothing longer:
+
+- Bucket: the slug
+- Memos: created N, updated N, deleted N
+- Not indexed: what and why, or "none"
+- Status: up to date, or what is left

package/skills/gigarecall/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: gigarecall
+description: Search GigaRAG and load what it knows into this conversation
+---
+
+Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.
+
+Recall what GigaRAG knows about: the text the user typed after the skill name
+
+If that is empty, ask me what to recall and stop.
+
+1. Call `search_nodes` with my question in plain words, limit 8. It combines exact-term and meaning-based search, so a paraphrase works as well as an identifier.
+2. Read the two to four most relevant hits in full with `fetch_node`. Search returns only a snippet, so do not answer from snippets alone.
+3. If a memo links to another that looks necessary to answer, read that one too with `fetch_node`, or use `neighbors`. Stop after about six memos in total.
+4. Give me what you found: the facts that answer the question, each with the ref of the memo it came from, like N:12. Say which memos disagree, if any do, and which is newer. If a memo is marked superseded, say so and prefer what replaced it.
+
+If nothing relevant came back, say that plainly and suggest one different phrasing to try. Do not fill the gap from general knowledge, and do not save anything.

package/skills/gigasave/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: gigasave
+description: Save this session's decisions and discoveries to GigaRAG as memos
+---
+
+Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.
+
+Save what this session decided or learned into GigaRAG, so the next session, on any machine or in any client, can find it. If I gave a focus ("the text the user typed after the skill name"), save only that. Otherwise go through the whole conversation.
+
+Find the bucket first: run `gigarag repo --slug` and use that slug. If no bucket has it yet, create one with that slug.
+
+What is worth a memo:
+- A decision, with why it was made and what was rejected. "We chose X over Y because Z" is the best kind.
+- A discovery that took effort: why something behaves as it does, a constraint nobody wrote down, a bug's real cause.
+- A convention agreed for this codebase.
+- An open question somebody still has to answer.
+
+What is not: chatter, status updates, anything already obvious from the code or the git log, and anything secret. Never save keys, tokens, passwords or personal data, even if they appeared in the conversation.
+
+For each one:
+1. Call `search_nodes` with the topic first. If a memo already covers it, update that memo with `update_node`, keeping the links already in its text, instead of creating a second one.
+2. Otherwise `create_node` in a thread called `decisions` in that bucket (create the thread if it is missing). Use the type `decision` for decisions and `note` for everything else. Set `actor` to `agent:claude-code`.
+3. The title states the point ("Use cursor pagination for /events"), not the topic ("Pagination"). The summary is one or two sentences. The body has the context, the decision, why, and what was rejected.
+4. Where a memo relates to another, link it in the text as `[Title](N:12)`, using the ref from `find_nodes`. Never write a UUID as a link target.
+
+At the end, list what you saved as one line each: the ref, the title, and whether it was created or updated. If there was nothing worth saving, say so and save nothing.

package/skills/gigasync/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: gigasync
+description: Bring GigaRAG up to date with the files that changed since the last index
+---
+
+Run the CLI as `gigarag`. If the shell says it is not found, use `npx -y gigarag` in its place, with the same arguments.
+
+This needs a shell tool, because it runs the `gigarag` command. If you have no way to run shell commands, say so in one sentence and stop. Do not guess at what the repository contains.
+
+Run `gigarag scan --summary` in the current directory and read the counts.
+
+If nothing is new, changed or gone, say "GigaRAG is up to date with this repository." and stop.
+
+Otherwise do an incremental sync yourself, in this conversation, following the procedure below and touching only the files the scan reports. When you finish, tell the user in three lines or fewer what changed: memos created, updated and deleted.
+
+## Procedure
+
+The work is split on purpose. The `gigarag` command does the mechanical half: it walks the tree, respects gitignore, hashes contents, plans chunk boundaries and works out what changed. You do the judgement half: what a module is for, what is worth summarising, and what links to what. Never walk the filesystem yourself with ls or find. The manifest names every file you need.
+
+## 1. Scan
+
+Run `gigarag scan <path>` with the path you were given, or the current directory. 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).
+- `removed` lists files that are gone, each with `nodeIds` and `deleteNodeIds`.
+- `truncated: true` means the walk hit its limit. Tell the user in your report and carry on with what you have.
+
+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.
+
+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.
+
+## 3. Write the memos
+
+Work in batches of about ten files. For each file:
+
+- Read it with the Read tool. When it has `chunks`, read one range at a time using `offset` and `limit`.
+- Write a memo that explains the file to somebody who has not read it. Cover what it is for, its public surface (exported names and signatures, not their bodies), how it connects to the rest of the system, and any non-obvious constraint. Aim for 500 to 2,500 characters. Do not paste the source. A memo that only restates the code is worse than none.
+- Very small files that only make sense together, such as a folder of three tiny helpers, may share one memo. Give each of those files the same node when you record them.
+- 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.
+- 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:
+
+{"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}]}]}
+
+`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.
+
+## 5. Remove what is gone
+
+For each entry in `removed`, call `delete_node` for every id in its `deleteNodeIds`. For memos that other files still feed, use `update_node` to take the removed file out of the text. Then record it:
+
+{"repo":"<slug>","removed":[{"path":"src/old.ts","deletedNodeIds":["<node id>"]}]}
+
+Without this half the index only ever grows and drifts away from the repository while still looking correct.
+
+## Rate limits
+
+If a tool answers that you are rate limited, wait and continue. Do not start over. Files you have already recorded are skipped by the next `gigarag scan`, so an interrupted index resumes where it stopped.
+
+## Report
+
+End with this, and nothing longer:
+
+- Bucket: the slug
+- Memos: created N, updated N, deleted N
+- Not indexed: what and why, or "none"
+- Status: up to date, or what is left