Update to Thegram

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,96 +1,44 @@
 ---
 name: thegram-cloud
-description: Read and write Thegram memory with the vault_* tools. One method answers from the person's vaults and from every GramHub shared dataset with the right scope and filters, and, when the person asks to save, records facts as typed records in the right .gram document without write errors.
+description: Load first whenever the person says record, save, note, remember, 기록, 저장 or 남겨, or names a Thegram vault or folder (the vaults listed in the Thegram server instructions, e.g. "Thegram-dev docs"); those go to Thegram, never to local files. Also for any question about the person's notes, projects, decisions or tasks, any question about shared reference data in GramHub, and before any Thegram tool call (vault_ask, vault_read, vault_add, vault_change, vault_exact).
 ---
 
-# Thegram
+# Thegram: how to read and record
 
-Tools (host prefixes allowed): reads `vault_browse`, `vault_search`, `vault_read`, `vault_changes`, `vault_comments`, `vault_guide`; writes `vault_create`, `vault_edit`, `vault_delete`, `vault_restore`, `vault_move`, `vault_comment`, `vault_feedback`. A ref is `@mounts/<vault>/<folder>/<doc>.gram`, a record `…gram#<id>`, a section `…gram§<heading>`; use refs exactly as tools return them. Answer in the person's language and cite `path#id`.
+For the five-tool surface only: `vault_ask` (read; `op` `ask` default, `hubs`, `browse`, `changes`, `comments`, `guide`), `vault_read`, `vault_add` (`op` `create`, `comment`, `restore`, `feedback`), `vault_change` (`op` `edit`, `move`, `delete`), `vault_exact`. If the tools listed to you have other names, this skill does not apply: follow the server's instructions.
 
-## 1. Scope first
+The rules below keep reads honest and records clean; when one cannot be met, do the rest and say exactly what is missing.
 
-Call `vault_browse {}` once per conversation unless the person gave a ref. Each row has `ref`, `label`, `access` and top `folders`.
+## Step 1. Decide the target, every time, before any call
 
-- `access: "write"`: the person's and their organizations' vaults. `access: "read"` (`@mounts/hub-team-*`): shared GramHub datasets, read-only, often tens of thousands of documents, and new ones appear over time. There is no fixed list.
-- Always pass `folder` (a vault, hub or dataset folder ref) to `vault_search`, and `path` to `vault_browse {select}`. An unscoped search spans every vault and hub, is slow and mixes personal notes with public data.
-- Never walk folders with `vault_browse` to find a document: names are opaque and there can be thousands. Use only refs a tool returned; a guessed folder fails with `E_PATH`.
+- **Own vaults**: the person's and their organizations' notes, projects, decisions, tasks, meetings → `vault_ask {question}` with NO `scope`.
+- **Hubs** (`@mounts/hub-team-*`, read-only): public or reference datasets; there can be any number of them → `vault_ask {op:"hubs", question}` returns the closest hubs. Pick the one whose `label` and `folders` fit and ask with its ref as `scope`. None fits → say Thegram holds no such dataset.
+- Unsure → ask without scope first: the answer lists `scope.hub_candidates`; use one if the question is about reference data.
+- NEVER search a hub without its ref in `scope`. NEVER mix own vaults and hubs. NEVER use a ref no tool returned. Hits of the wrong kind (personal notes for a reference question, or the reverse) mean the wrong target: go back to Step 1.
 
-## 2. One way to read any vault or hub
+## Step 2. Read
 
-The same steps serve a personal vault and every hub. Nothing here depends on what a dataset holds.
+1. `question` = the person's words with every exact name, number and code. For a find, add `terms` (1–4 nouns every hit must hold). `terms` and `options` work ONLY with a find: NEVER send them with `plan.operation` `count`, `list` or `changes` (`E_ARGUMENT`).
+2. Filters (type, status, date, tag) go ONLY in `plan.conditions`, each with `quote` = the question's words it came from. NEVER invent a value. On `interpretation.unresolved`, use a value from `allowed` or ask the person.
+3. Hubs differ from vaults: document names are opaque ids, records carry `tags` as `key:value`, and a hub folder may hold `guide.gram` (field and date meanings) and `coverage.gram` (period covered). NEVER walk a hub's folders. Narrow by copying a tag exactly from a hit into `record.tag`. Read `guide.gram` / `coverage.gram` before stating what a hub field or date means or how current it is; if they do not exist, say the meaning or freshness is unconfirmed.
+4. A hit counts only if it matches EVERY entity the question names: same name, number, article or code. Another entity with the same number is not an answer.
+5. Use `records` and `hits` first; `vault_read` only what they lack.
+6. When an answer has `next`, call `next.tool` with `next.args` as given, even if that tool is not listed. NEVER build a cursor. If that call comes back `unresolved` or fails, apply Step 3 rule 8 before giving up.
 
-1. **Ask plainly.** `vault_search {query, folder}`; `query` is never empty. A sentence with the exact names, codes or numbers a record would hold. A named document or article is looked up directly and does not depend on the index.
-2. **Learn the dataset from one hit.** Hits carry `tags`, `at`, `due`, `observed`; otherwise `vault_read` one hit with `fields:["tag"]`. Tags are `key:value` exactly as stored: copy them from a hit, never guess a value. Every data record in a hub carries one `종류` tag (its kind); guide and source records carry none. `group_by:"종류"` with the question's words lists which kinds match and how many. A record without tags keeps the source row as JSON in `d`: filter it by words and dates. Date meanings differ per dataset; a dataset folder may hold `guide.gram` (meanings) and `coverage.gram` (period covered): read them with `vault_browse {path, ids:true}` and `vault_read` when meaning or freshness matters.
-3. **Narrow with structure.** `tag:["k:v", …]` (every tag must hold), `from`/`to` (`YYYY`, `YYYY-MM` or a date), `valid_at:"YYYY-MM-DD"`, `terms:[…]`, `group_by:"<tag key>"`, `per_group`, `type`, `status`, `limit` up to 20. `order:"-at"` returns the newest by `at` first and `"at"` the oldest first (for "latest", "first", "most recent"); the default ranks by match. `query` holds words from the record text, never a tag string.
-   - `terms` (one to four nouns every hit must hold) filter; `query` ranks. By default hits are ordered by how rare the `query` words are in a record; a word in the title counts three times, in a tag twice. Records holding the same words tie and keep document order, so the first hit can be any of them: put the distinguishing words in `query` too, choose by `title` and `tags`, and read before relying on one.
-   - `group_by` gives the size of each value of one tag key and a `next` call per group: it shows which kinds of record match and how many in one call. Report `candidates` instead of paging to count. Pair it with a tag that ties the records together (copied from a hit), or it groups every record the words touch. Leave out `related_by` unless asked.
-   - `valid_at` keeps records in force that day (`at` on or before it, `due` empty or after it). A later date returns what is scheduled; a date before the earliest stored record returns 0 candidates: say older records are not stored, and never present current text as valid on that day.
-4. **Read the answer's metadata every time.**
-   - `note` with `INDEX_PENDING`, or `coverage.files_pending` > 0: those documents are left out. Say the result is partial; for a lookup, ask again without filters, or later. `E_INDEXING`: nothing indexed yet, same remedy.
-   - `mode:"keyword"` with `reason:"WIDE_SCOPE_KEYWORD"`: a filtered wide search ranks by matching words, not meaning. Use the dataset's own words and check `matched` and `gaps`.
-   - `omitted` with `PAGE_LIMIT`, or `more`: call `next.tool` with `next.args` exactly; never build a cursor. Page only when the question needs every match (counts, lists, rankings) and say where you stopped.
-   - `relevance:"weak"`: the hits are only nearby; say the dataset may not hold the answer.
-   - `E_SCOPE_TOO_WIDE`: `as_of` and date fields other than `at`, `due`, `observed` need a small scope; pick a folder from `candidates` or name `documents`.
-5. **Open before quoting.** A hit's `summary` is cut short (for row datasets it is only the date). Call `vault_read {refs:[…]}` once with every ref you need (up to 16, `fields:["t","d","at","due"]`). Name the dataset, the ref and the record's date; hub data is a published snapshot, not live.
-6. **Conclude carefully.** Never answer "none found" from one empty or odd result: change the words or a tag spelling once. A kind absent from `groups` holds no record with all the `terms`: say so for those words. A result you already have that returned the kind still counts: check it first. Stop when the question is answered; page further only when asked.
-7. Hubs are never a write destination. Do not copy hub records into the person's vault unless asked.
+## Step 3. Answer
 
-## 3. More reads of one document
+7. Every claim cites `path#id`. No ref, no claim.
+8. Counts, totals, averages, maxima, top N: ONLY `vault_exact {query, folder}`. Its planner understands short phrases in the source's alias words, not long questions: if a call is `unresolved`, call `vault_exact {query, folder, exact:{catalog:true}}`, rewrite the query as `<condition words> <type alias> 개수` (e.g. `미해결 할 일 레코드 개수`, `할 일 개수`) using only listed aliases, and retry once. Accept ONLY `execution.status:"complete"`; `running` → call `next` until it ends. Still not complete → say there is no exact result and why. NEVER count hits.
+9. A complete exact result is exact only within its scope: if `coverage` or the source says upstream completeness is unknown, say so. Its snapshot (`execution.read_set`) expires in about 15 minutes: read rows with `vault_read {refs, snapshot}` before then, or rerun.
+10. Say plainly that a result is partial or approximate when it shows `relevance:"weak"`, `omitted`, `coverage.files_pending` > 0, unknown upstream coverage or `interpretation.exhaustive`. NEVER say "none exists" after one search.
+11. Hub data is a published snapshot: name the dataset and the record's date.
 
-- Links of one record: `vault_read {refs, relations:{direction:"both"}}`.
-- State: `vault_browse {path, summary:true}` gives open records, `rev`, `hash` and `next`; later `vault_changes {path, since: next}` gives only what changed.
-- All record ids: `vault_browse {path, ids:true}`, then `vault_read` the ids you need.
-- Lists: `vault_browse {path, select:{type, status, tag, from, to}}`.
+## Step 4. Record
 
-## 4. Writing, only when the person asks to save
-
-A writable connection is not permission: save only what the person asked, where they asked or where the subject already lives. Never switch to another vault after a refusal.
-
-Every write:
-
-1. Read the records you will change (`vault_read`, `fields:["t","d","x"]`). `set` and `unset` carry `old`, the exact value read (`null` when empty).
-2. Send one `vault_edit {path, request_id, operations}` per coherent change, with a new stable `request_id` per intended change. Reuse a `request_id` only to repeat the same call.
-3. While the answer says `sync.state: "queued"`, repeat the identical call; it usually settles within 5–20 seconds. The write landed only at `"synced"`: then `vault_read` the changed records.
-
-Records:
-
-- `type` is one of: project goal requirement assumption decision task blocker risk event artifact evidence metric component system service source history knowledge context person agent run. Any other word, `note` included, fails (with a misleading `E_DUPLICATE_FIELD`).
-- Every record needs `t`, a short title, never a date or id. Field values are arrays: `{"t":["…"],"d":["…"]}`; `d` is one self-contained sentence of the outcome.
-- `x` values: task backlog, open, active, review, blocked, waiting, completed, cancelled, archived; goal open, active, completed, cancelled, archived; project planning, active, at-risk, on-hold, completed, cancelled, archived; decision proposed, accepted, rejected, superseded; risk open, mitigated, resolved, accepted, closed. These five types require `x`. An event requires `at` (ISO date or time; `x` confirmed, tentative, cancelled), a metric `value` and `unit`, an artifact `ref`.
-- `id`: lowercase letters, digits and `-` with a type prefix (`task-…`, `dec-…`, `risk-…`); no dots, spaces or dates.
-- Links: `[["part-of","prj-x"]]` with part-of, implements, depends, derives, related, supports, contradicts, replaces, blocks, enables. The target must exist or be added earlier in the same call.
-- A status change is `set x` with `old`, never a new record. A full replacement sets the old record `superseded` and links `replaces` from the new one. Never remove a record that was true.
-- `ref` is one URL others can open, never a local path; `source` holds `source` record ids.
-
-Operations:
-
-- add: `{"op":"add","record":{"type":"task","id":"task-x","fields":{"t":["…"],"x":["open"]},"links":[["part-of","prj-y"]]},"place":{"section":"<existing heading>"}}`. `place` may also be `{"after":"<id>"}` or `"end"`; the section must already exist.
-- set: `{"op":"set","entity":"task-x","key":"x","value":"completed","old":"active"}`
-- prose: `{"op":"edit-text","entity":"doc","kind":"rich","old":"<exact text occurring once>","new":"…"}`. Never in the same call as an `add` with `place`; add records first, edit prose in the next call.
-- New section, or a change to the last section: `edit-text` anchored on the last line of the body, e.g. `"old":"[[last-id]]"`, `"new":"[[last-id]]\n\n# Heading\n\nText"`. The `section` op works only on an existing section that is not the last, with `base_revision` and `expected_hash` from `vault_read {refs:["<path>§<heading>"], source:true}`. A source read of the last section ends with internal `@ids` lines: never copy them into new text.
-- remove, and replacing the whole body, need `base_revision` and `expected_hash` (the `rev` and `hash` of `vault_browse {path, summary:true}`).
-
-New document: first check that none on the subject exists. Then `vault_create {path, title, base_revision:null, request_id, content:{text, records}}` with a short ASCII slug filename in an existing writable folder, headings in `text` and each record's `[[id]]` alone on a line where it should appear.
-
-## 5. Errors: fix the cause, never resend unchanged
-
-| code | fix |
-|---|---|
-| `E_PRECONDITION` | `details.conditions` shows the actual value or the missing anchor: reread, decide, resend with a new `request_id` |
-| `E_TEMPLATE` | `details.diagnostics` names the record, field and allowed values |
-| `E_ARGUMENT` | missing `old`, `place` mixed with a body edit, or a wrong shape |
-| `E_SYNTAX` | an id, link target or field key holds a bad character, usually a dot |
-| `E_MISSING_TARGET` | add the link target first, in the same call |
-| `E_AMBIGUOUS_TEXT` | `old` must occur exactly once: copy a longer exact span from a `source:true` read |
-| `E_CAS_REQUIRED` | add `base_revision` and `expected_hash` from a fresh summary |
-| `E_REQUEST_REUSE` | that `request_id` carried different content: use a new one |
-| `E_RICH` "Invalid @ids line" | a `section` op reached the end of the body: use the `edit-text` append above |
-| `E_LONG_PARAGRAPH` | a paragraph would pass 1,000 characters: put new detail in its own paragraph |
-| `STALE_CURSOR` | the documents changed: rerun from the first page |
-| `AGENT_SCOPE_DENIED`, `E_READ_ONLY`, `E_FORBIDDEN`, `E_PATH` | stop and tell the person (Thegram Settings → Connected agents); never write elsewhere |
-
-A write answer may carry `decision_analysis` suggestions. They are never applied and need no action.
-
-## 6. Report
-
-Name the refs you relied on. For a write, give the document path, the new revision and the changed record ids after the readback. Say plainly what was partial: index pending, pages left unread, weak relevance.
+12. The destination is a Thegram vault, never a local file or repository document. A vault or folder the person names ("Thegram-dev docs") is one of the vaults in the server instructions; if none is named and it is unclear, ask which vault. The content comes from the conversation and from anything you can read: for a repository, project or file, look for it by name where you can (working directory, its parent and siblings, home directory) and read its README, design notes and manifest first. When you record, what the person said is enough (the name, that it exists, today's date); add what sources state, cite them, and name what is still unknown. Asking for more never replaces writing what you have.
+13. Before the first write in a conversation call `vault_ask {op:"guide", task:"memory"}` and follow it.
+14. Add to the existing document on the subject; `vault_add {op:"create"}` only when none exists. Hubs are read-only: never write there.
+15. One record per fact. `type` is one of: knowledge evidence context history assumption source decision requirement goal task project blocker run risk metric event person agent system service component artifact. When unsure, pick the closest; `knowledge` fits any plain fact.
+16. Before changing a record, `vault_read` it. Status: `set x` with `old` = the value read. Mark a replaced record `superseded` instead of deleting it.
+17. Every write has a new `request_id`. On `sync.state:"queued"`, resend the identical call until `"synced"`, then `vault_read` it and report path, revision and record ids.
+18. On an error, fix the cause from `details` and retry; never resend unchanged. If the write still cannot land (no write access, the vault refuses), keep the full content in your answer and tell the person where it could not be saved and why; do not save it somewhere else on your own.