1. Query before you think. At the start of any non-trivial task, retrieve what the project already knows so you don't re-derive or contradict it.
2. Curate after you implement. When you finish something worth remembering (a decision, a gotcha, a pattern), write it back so the next session inherits it.

<bv-*>

node scripts/query.mjs "<question>" --limit 5

node scripts/record.mjs "<topic-path>" --html '<bv-topic …>…</bv-topic>'

node scripts/record.mjs "<topic-path>" --title "T" --summary "S" --keywords a,b --body "..."

node scripts/record.mjs --batch --input <ndjson-file>

{"path":"...","html":"<bv-topic …>…</bv-topic>","overwrite"?:true}

failed[]

Required

<bv-topic>

attributes:

path

and

title

MUST be present and non-empty on the topic root or the writer rejects the call. The

path

on

<bv-topic>

should match the positional

<topic-path>

you pass to

record.mjs

. See vocabulary.md for the full attribute spec. | Read |

node scripts/brv.mjs read "<topic-path>.html" [--raw]

(use

--raw

to get the on-disk HTML byte-for-byte — required when round-tripping through

record --html

, since

elements[].text

flattens inner

<ul>

/

<li>

/

<strong>

formatting) | | List |

node scripts/brv.mjs list

| | Rebuild manifest + index |

node scripts/manifest.mjs

| | Detect consolidation opportunities |

node scripts/dream.mjs --mode merge\|link\|prune\|synthesize

(proposes — never executes) | | Fold one topic into another |

node scripts/merge.mjs <survivor> <loser> [--title "…"] [--summary "…"] [--tags a,b] [--keywords a,b] [--reason "…"] [--related @x.html,@y.html]

(use

--title

to give the survivor a new title that reflects the merged scope — without it, the survivor keeps its own title even when the merged content is broader) | | Remove redundant topics |

node scripts/prune.mjs <topic-path>...

(variadic, atomic — aborts on first failure with a partial report) | | Combine many topics into a new one |

node scripts/synthesize.mjs <new-path> --html '<bv-topic …>…</bv-topic>' --absorb a.html,b.html,c.html

| | Rename / move / re-parent a topic within the current space |

node scripts/move.mjs <topic-path> --to-path <new-path>

(atomic — siblings'

related=

refs are rewritten to the new path; signal sidecar carries over; covers all of rename, move-to-new-parent, deep re-parent, and combined) | | Add or remove a

related=

cross-link between two topics |

node scripts/brv.mjs link "<a>" "<b>" [--bidirectional] [--remove]

(atomic byte-preserving edit of the

<bv-topic related="…">

attribute — use this instead of hand-editing the opening tag, which is unsafe for summaries containing

>

characters; idempotent — re-linking is a noop; refuses to add a ref to a topic that doesn't exist (would dangle) — but

--remove

allows missing targets so you can clean up existing dangling refs) | | Move a topic to a different space |

node scripts/move.mjs <topic-path> --from-space <name> --to-space <name>

(rebuilds manifest + index in both spaces; reports any sibling

related=

refs in the source that now dangle) | | Migrate legacy markdown |

node scripts/migrate.mjs [--dry-run]

| | Migrate a self-hosted v3 VPS → v4 (full guided procedure) | follow migrate-v3-to-v4.md | | Authenticate / log in to ByteRover |

node scripts/auth.mjs

— returns at once; the user approves in the browser, then

auth.mjs status

; see Authenticate with ByteRover | | Check whether signed in (local, no network) |

node scripts/auth.mjs whoami

— prints

{ ok, authed, providerKind }

(a credential exists locally; not a server-side validity check) | | Log out of ByteRover |

node scripts/logout.mjs

| | See which space this folder uses |

node scripts/space.mjs current

| | List spaces (grouped by

team_name

) |

node scripts/space.mjs list

| | Bind this folder to a space |

node scripts/space.mjs bind "<name>"

|

{ "ok": false, ... }

query

citation_block

should_cite: true

1. Add ONE blank line after your answer.
2. Emit the

   citation_block

   string verbatim — character for character — including the

   […](…)

   Markdown link wrapping each title, the indented

   "snippet"

   line when present, and the

   Updated by <agent> · <relative>

   trailer when present. Every host the engine targets (Codex CLI, Claude Code CLI, Claude Code Desktop) renders the wrapped title as a clickable inline link.
3. Don't reformat, paraphrase, or add agent-generated relevance scores to the citations. The user judges relevance from the title.
4. Do NOT unwrap the Markdown link. The engine deliberately emits

   - [Title  ·  Recalled N×](http://…)

   — rewriting it as a plain title with the URL on a separate row undoes the format that hides the long URL behind clickable text. Same rule for the snippet and updated-by lines: keep them indented exactly as the engine emitted them, never merged into the title row or stripped of their leading spaces.

should_cite

false

📚 …

ATM: Er Rak Error is a 2012 Thai romantic comedy by Mez Tharatorn …

📚 From ByteRover:
- [ATM: Er Rak Error (2012 Thai film) (fact)  ·  Recalled 14×](http://127.0.0.1:<port>/i/topic/<space-id>/context-tree/movies/atm_er_rak_error.html#bve-a1b2c3d4)
    "matched-context preview that explains why this hit ranked here"
    Updated by claude · 3d ago
- [Pee Mak Phra Khanong (2013) (highlights)](http://127.0.0.1:<port>/i/topic/<space-id>/context-tree/movies/pee_mak_phra_khanong.html#bve-e5f6g7h8,k1m2n3p4)

node scripts/auth.mjs

{ "ok": true, "pending": true, "verifyUrl": …, "userCode": …, "expiresInS": … }

verifyUrl

expiresInS

node scripts/auth.mjs status

• { "state": "approved" }

  → connected; tell the user.

• { "state": "pending" }

  → not through yet — ask them to finish the browser step (the result re-includes

  verifyUrl

  ) and say so again.

• { "state": "expired" }

  → the code died; run

  node scripts/auth.mjs

  again for a fresh one and re-relay it.

• { "state": "denied" }

  → the user declined; stop and surface it.

auth.mjs

"reused": true

node scripts/logout.mjs

node scripts/auth.mjs --key-file <path>

node scripts/auth.mjs --wait

auth.mjs

{ "ok": false }

<bv-*>

## Reason

<bv-reason>

## Raw Concept

<bv-task>

<bv-changes>

<bv-files>

<bv-flow>

<bv-timestamp>

<bv-author>

<bv-pattern>

## Narrative

<bv-structure>

<bv-dependencies>

<bv-highlights>

<bv-rule>

<bv-examples>

<bv-diagram>

## Facts

<bv-fact>

<bv-decision>

<bv-bug>

<bv-fix>

1. A

   <bv-reason>

   explaining the WHY of the curation (the topic isn't useful without context for why it was captured).
2. A

   <bv-task>

   describing what the topic is about (one sentence), OR an

   <h1>

   + intro

   <p>

   if "task" doesn't fit.
3. At least one Narrative or Raw Concept element beyond the task:

   <bv-changes>

   /

   <bv-files>

   /

   <bv-flow>

   /

   <bv-structure>

   /

   <bv-dependencies>

   /

   <bv-highlights>

   /

   <bv-decision>

   /

   <bv-bug>

   /

   <bv-fix>

   . A topic with only

   <bv-fact>

   siblings is a placeholder, not a topic.

4. <bv-timestamp>

   in ISO 8601 if the content has a reference date.

5. <bv-fact subject="snake_case" category="…" value="…">canonical statement</bv-fact>

   for each extracted fact —

   subject

   is snake_case,

   category

   is one of

   personal

   /

   project

   /

   preference

   /

   convention

   /

   team

   /

   environment

   /

   other

   ,

   value

   carries the extracted form, and the body text is the canonical natural-language statement (not a label).

node scripts/record.mjs "movies/atm_er_rak_error" --html '
<bv-topic path="movies/atm_er_rak_error"
          title="ATM: Er Rak Error (2012 Thai film)"
          summary="GTH 2012 romantic comedy by Mez Tharatorn — secretly-dating bank employees bet their jobs on recovering money from a malfunctioning ATM."
          keywords="atm_er_rak_error,gth,thai_romcom,mez_tharatorn,2012"
          tags="film,thai,gth,romcom"
          related="@movies/pee_mak_phra_khanong.html">

  <bv-reason>
    Anchor topic for cross-references between Thai GTH romcoms; documents
    the studio box-office record holder before Pee Mak (2013).
  </bv-reason>

  <bv-task>Profile of ATM: Er Rak Error (2012) — credits, plot, awards, legacy.</bv-task>

  <bv-timestamp>2012-01-19</bv-timestamp>

  <bv-highlights>
    Premise: a bank no-fraternization policy forces a secret 5-year couple
    into a winner-keeps-the-job bet over money from a glitching ATM.
    Was GTH biggest hit until Pee Mak (2013) topped it.
  </bv-highlights>

  <bv-structure>
    <p>Credits:</p>
    <ul>
      <li><strong>Director:</strong> Mez Tharatorn</li>
      <li><strong>Writers:</strong> Mez Tharatorn, Aummaraporn Phandintong</li>
      <li><strong>Studio:</strong> GTH (GMM Tai Hub)</li>
    </ul>
    <p>Lead cast:</p>
    <ul>
      <li><strong>Sua:</strong> Ter Chantavit Dhanasevi</li>
      <li><strong>Jib:</strong> Ice Preechaya Pongthananikorn</li>
    </ul>
  </bv-structure>

  <bv-flow>
    Sua and Jib are bank staff who dated secretly for 5 years under the
    bank no-fraternization policy. An ATM glitches and dispenses 130,000
    baht. They bet: whoever recovers the money keeps their job. The
    sequence escalates into a chaotic showdown involving manager Pakorn,
    Sergeant Sam, and Sam pet crocodile Jack.
  </bv-flow>

  <bv-fact subject="release_date" category="project" value="2012-01-19">
    The film was released theatrically in Thailand on January 19, 2012.
  </bv-fact>

  <bv-fact subject="runtime_minutes" category="project" value="123">
    The film runs 123 minutes.
  </bv-fact>

  <bv-fact subject="box_office" category="project" value="150.11 million baht">
    The film grossed 150.11 million baht, reaching Thailand 7th highest-
    grossing film within four weeks of release.
  </bv-fact>

  <bv-fact subject="record_vs_pee_mak" category="project" value="GTH highest-grossing film until Pee Mak (2013)">
    ATM was GTH/GMM Tai Hub highest-grossing film until Pee Mak surpassed it in 2013.
  </bv-fact>

  <bv-changes>
    <li>2013-11-30 to 2014-02-08: TV sequel ATM 2: Koo ver Error Er Rak aired (21 episodes, One 31).</li>
    <li>Chinese-language remake released as Welcome to the Beartown.</li>
  </bv-changes>

</bv-topic>'

• <bv-reason>

  carries the WHY of this curation. Missing this is the single most common authoring failure — don't skip it.

• <bv-task>

  +

  <bv-timestamp>

  carry the WHAT and WHEN.

• <bv-highlights>

  +

  <bv-flow>

  carry the HOW (the explanation, the process).

• <bv-structure>

  carries grouped lists like cast/credits/file layouts — NOT a pile of

  <bv-fact>

  siblings. Reserve

  <bv-fact>

  for discrete queryable claims (release date, runtime, box office, awards).

• All attribute values are double-quoted strings. Not single quotes.
• All attribute names are lowercase.
• Path segments are snake_case with underscores between words:

  movies/atm_er_rak_error

  , NOT

  movies/atm-er-rak-error

  (hyphens).

• related=

  uses

  @path.html

  for file targets,

  @path

  bare for folder/domain targets. The

  @

  prefix is required.
• No code fence wrapper. The

  --html

  argument is bare HTML — first character

  <

  , last characters

  </bv-topic>

  . No

  ```

  , no

  ```html

  .
• Don't set

  createdat

  ,

  updatedat

  ,

  id

  ,

  importance

  ,

  maturity

  , or

  recency

  on

  <bv-topic>

  . The writer system-stamps the first three; the last three are sidecar runtime signals the LLM does not author.
• Don't invent custom elements outside the 19-element

  <bv-*>

  vocabulary, or attributes outside each element's documented schema.

<bv-fact disclosure="public">

disclosure="public"

• <bv-fact>

  is the SOLE unit of per-item restriction. The topic

  title

  and all prose text (inside

  <bv-structure>

  ,

  <p>

  ,

  <bv-flow>

  ,

  <bv-highlights>

  , etc.) are public-by-contract — they survive the redacted view verbatim. Never put a secret in the title or in prose; move it into a

  <bv-fact>

  (which can then default to restricted).
• Absent or misspelled

  disclosure

  is treated as restricted. Fail- closed: a typo never accidentally publishes, but it can accidentally hide. Double-check the spelling.

• <bv-topic visibility>

  does NOT make facts public. It's an informational label only. The redacted view consults each fact's own

  disclosure

  attribute, never the topic-level default.

• Simple form (

  --title --body

  ) wraps the body in a single

  <bv-fact>

  . Use it ONLY when the topic is genuinely one fact ("we use OAuth 2.0 with PKCE"). For anything else the wrapper structure is wrong.
• Rich form (

  --html

  ) is everything else — profile dumps, decisions+reasons+rules+facts, bug+fix runbooks, research notes.

• First time in a repo, or no memory exists for the project → onboarding.md
• Before retrieving → query.md
• Before saving knowledge → record.md
• Choosing the right

  <bv-*>

  element → vocabulary.md
• Periodic cleanup / consolidation → dream.md

Note: topics are

<bv-*>

HTML (not markdown).

scripts/*.mjs

are generated from

@byterover/skill-runtime

by

pnpm build:skill

; if missing, build first.