@andespindola/brainlink 0.1.0-alpha.2 → 0.1.0-alpha.4

package/AGENTS.md

@@ -27,12 +27,16 @@ By default, the installed Brainlink CLI uses `$HOME/.brainlink/vault` as its vau
 Use this loop when using Brainlink as memory:
 
 1. Write durable knowledge into Markdown notes.
-2. Link related notes with `[[Note Title]]`.
+2. Link related notes with explicit `[[Note Title]]` wiki links inside the note body.
 3. Add explicit `#tags` for retrieval.
 4. Run `index` after writes.
 5. Run `context "<task or question>"` before answering.
 6. Use the returned sources as grounded context.
 
+`context` is read-only. It does not create notes, backlinks, graph edges or durable memory by itself. A relationship exists only when a Markdown note contains a `[[wiki link]]` to another note and the vault has been indexed after that write.
+
+When an agent adds durable memory, it should connect the new note to at least one existing concept unless the note is intentionally a root concept. Prefer exact note titles in links, for example `[[Architecture]]`, and run `broken-links`, `orphans` or `validate` when the graph looks disconnected.
+
 ## Commands
 
 ```bash

package/README.md

@@ -76,7 +76,7 @@ Requirements:
 - npm
 
 ```bash
-npm install -g @andespindola/brainlink
+npm install -g @andespindola/brainlink@latest
 ```
 
 The package installs two equivalent commands:
@@ -88,6 +88,14 @@ blink --help
 
 Use `brainlink` when clarity matters. Use `blink` for faster daily terminal usage.
 
+The npm package page may show `npm i @andespindola/brainlink`. That installs
+Brainlink as a project dependency. Use `-g` when you want the terminal commands
+available globally, or run it without a global install:
+
+```bash
+npx @andespindola/brainlink@latest --help
+```
+
 ## Agent Autonomous Setup
 
 This section is written for agents. If you are an AI agent operating in a user workspace, use this workflow to install and use Brainlink without requiring the user to run commands manually.
@@ -101,7 +109,7 @@ command -v blink || command -v brainlink
 If neither command exists, install it:
 
 ```bash
-npm install -g @andespindola/brainlink
+npm install -g @andespindola/brainlink@latest
 ```
 
 Then verify:
@@ -177,6 +185,15 @@ blink add "Testing Policy" \
   --content "Run npm run check before final delivery. Related: [[Release Checklist]]. #testing #process"
 ```
 
+Brainlink does not infer durable graph relationships from generated context. A context result is only a read package for the model. To create a real link in the knowledge graph, the agent must write Markdown that contains an explicit `[[Note Title]]` wiki link and then rebuild the index.
+
+When adding memory, follow this contract:
+
+- Link the new note to at least one existing note when there is a related concept.
+- Use the exact target note title inside `[[...]]`.
+- Add retrieval tags such as `#architecture`, `#decision`, `#runbook` or `#preference`.
+- Do not leave isolated notes unless they are intentionally root concepts.
+
 Rebuild the index:
 
 ```bash
@@ -199,9 +216,9 @@ Use this loop during real work:
 2. Run `blink context "<task>" --agent "$BLINK_AGENT" --json`.
 3. Use returned sources as project memory.
 4. Perform the task.
-5. Save only durable learnings with `blink add`.
+5. Save only durable learnings with `blink add`, including `[[wiki links]]` to related notes.
 6. Run `blink index`.
-7. Validate with `blink validate`.
+7. Validate with `blink validate`, `blink broken-links` and `blink orphans` when graph links matter.
 
 Do not store secrets, credentials, private keys, access tokens or transient chat noise.
 

package/docs/AGENT_USAGE.md

@@ -138,6 +138,41 @@ Rules:
 - Prefer summaries over raw transcripts.
 - Preserve dates when the timing matters.
 
+## Linking Contract
+
+Brainlink only builds graph edges from Markdown `[[wiki links]]`.
+
+The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
+
+Required write behavior:
+
+1. Choose a clear title for the new note.
+2. Look for an existing related concept with `search`, `links` or `backlinks`.
+3. Add at least one `[[Existing Note Title]]` link unless the note is intentionally a root concept.
+4. Add useful `#tags` for retrieval.
+5. Run `index` after the write.
+6. Run `validate`, `broken-links` or `orphans` when the graph should be connected.
+
+Good linked note:
+
+```bash
+blink add "SQLite Index Rebuild" \
+  --agent coding-agent \
+  --content "Legacy derived indexes without agent columns are rebuilt because SQLite is disposable. Related: [[Architecture]], [[Agent Namespaces]]. #sqlite #architecture #decision"
+blink index
+blink validate --agent coding-agent
+```
+
+Poor disconnected note:
+
+```bash
+blink add "SQLite Index Rebuild" \
+  --agent coding-agent \
+  --content "We rebuild old indexes now."
+```
+
+The poor note may be searchable, but it will not create graph links, backlinks or useful traversal paths.
+
 ## Read Policy
 
 Before answering a memory-dependent question, run:
@@ -453,6 +488,12 @@ Output:
 
 Agents should include source paths in their reasoning or final answer when the user needs traceability.
 
+Non-goals:
+
+- `context` must not be treated as a write operation.
+- Retrieved context must not be assumed to create graph edges.
+- Backlinks are derived only from indexed `[[wiki links]]`.
+
 ## Operational Rules
 
 - Re-run `index` after modifying notes.
@@ -461,6 +502,8 @@ Agents should include source paths in their reasoning or final answer when the u
 - Do not manually edit the database.
 - Keep generated context short enough for the target model.
 - Prefer specific queries over broad queries.
+- Write explicit `[[wiki links]]` when durable memory should be connected.
+- Check `orphans` before assuming the graph is healthy.
 
 ## Failure Modes
 

package/docs/RELEASE.md

@@ -49,6 +49,7 @@ The preferred path is the `Publish npm` GitHub Actions workflow:
 
 - GitHub Release `published`: runs checks, pack smoke, then publishes to npm with provenance.
 - Manual `workflow_dispatch`: runs a dry run by default. Disable `dry_run` only for an intentional manual publish.
+- Manual `workflow_dispatch` accepts an optional `dist_tag` override. Use `latest` only when the default npm install command should resolve to that version.
 - Prerelease versions publish under their prerelease dist-tag, for example `0.1.0-alpha.1` publishes with `--tag alpha`.
 
 For emergency local publishing of scoped public packages:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",