# Reported issues for vnsh

Pod holds 16 of 18 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [vnsh](/mcp/vnsh).

## Most discussed

### Add search, filtering and knowledge discovery across accessible documents

Parent: #49

## Problem

A knowledge system that requires users and agents to already know every URL is not discoverable.

## V1 scope

- Search non-sensitive metadata: title, tags, type, status, author and timestamps.
- Filter by space, collection, type, tag, status and recency.
- Provide recent/changed-since queries for agent synchronization.
- Add browser search plus CLI and MCP search/list operations.
- Define pagination, stable ordering and result snippets.
- For encrypted body search, begi

[Read the thread](https://github.com/raullenchai/vnsh/issues/53) · 2026-08-13 · open · 2 comments

### Decision gate: does more than one agent actually touch a workspace?

The gate for the whole v2 bet:

```sql
SELECT blob3 AS workspace, count(DISTINCT blob4) AS agents
FROM vnsh_events
WHERE blob1 LIKE 'workspace%'
GROUP BY workspace
```

`blob4` is the agent identity, taken from the MCP `initialize` handshake. It has
to be counted rather than `blob2` (client type): every MCP client reaches vnsh
through the same server and reports `mcp`, so counting client types would show 1
for three collaborating agents and 2 for a single agent using two surfaces —
wrong in both

[Read the thread](https://github.com/raullenchai/vnsh/issues/16) · 2026-07-28 · open · 2 comments

### Artifact V1: add cross-surface create, update, review-request and handoff operations

Parent: #59

## Goal

Give browser, CLI and MCP one coherent collaboration contract instead of implementing Artifact semantics independently.

## Operations

- create Artifact;
- get/list/search;
- read current or selected version;
- update with expected version;
- attach change summary and evidence;
- request human review;
- hand off with principal, instruction and per-Artifact scope;
- inspect capabilities and status.

## Design constraints

- Use one canonical validation/URL/version package w

[Read the thread](https://github.com/raullenchai/vnsh/issues/65) · 2026-08-13 · open · 1 comment

### Migrate existing permanent workspaces and artifacts into Knowledge Spaces safely

Parent: #49

## Goal

Introduce Knowledge Spaces without breaking existing permanent URLs, ownership, encryption, history or automation.

## Scope

- assign existing permanent documents to a default personal space;
- backfill safe metadata defaults;
- preserve all `/w/`, `/artifact/`, `/p/`, `#w=` and `#r=` URLs;
- define opt-in conversion from URL-key encryption to managed-space encryption;
- preserve version history, quota accounting and public/private visibility;
- update account UI, API, CLI

[Read the thread](https://github.com/raullenchai/vnsh/issues/58) · 2026-08-13 · open · 1 comment

### Expose vnsh knowledge as MCP Resources and add project bootstrap

Parent: #49

## Goal

Make vnsh knowledge discoverable through standard MCP primitives, not only callable tools that require a preexisting URL.

## Scope

- Advertise MCP Resources and Resource Templates for spaces, documents and artifacts.
- Support list/read discovery with stable vnsh resource URIs.
- Keep mutating behavior in tools.
- Add a bounded project-bootstrap operation/resource that returns:
  - project overview;
  - current-state and handoff documents;
  - active decisions and runbook

[Read the thread](https://github.com/raullenchai/vnsh/issues/54) · 2026-08-13 · open · 1 comment

### Self-describing responses: Link rel=describedby, and workspaces in /llms.txt

An agent that meets a `vnsh.dev/w/` link with no vnsh tooling installed has no way
to learn what to do with it. `/llms.txt` documents this, but nothing points there
from the resource itself.

Adding a `Link` header to workspace and blob responses lets an agent bootstrap
from the response alone, with no prior knowledge and nothing installed:

```
Link: <https://vnsh.dev/llms.txt>; rel="describedby"
```

This is the widest tier of the distribution ladder: it reaches every agent that
can make an HT

[Read the thread](https://github.com/raullenchai/vnsh/issues/26) · 2026-07-28 · closed · 1 comment

### No per-directory agent guidance (AGENTS.md)

There is a root `CLAUDE.md` and nothing else. `worker/`, `mcp/`, `cli/`,
`extension/` and `tests/` have no local guidance about conventions, test commands,
security constraints or the traps specific to each.

Several traps in this repo are non-obvious and have each cost real time:

- **`worker/`** — client JS lives inside TypeScript template literals, so
  backslashes must be doubled or regexes silently break at runtime. Neither the
  type checker nor unit tests catch it.
- **`worker/test/`** — 

[Read the thread](https://github.com/raullenchai/vnsh/issues/24) · 2026-07-28 · closed · 1 comment

### Version metadata disagrees across package.json, server.json, runtime and client headers

Version strings disagree across the MCP package:

| Where | Value |
|---|---|
| `mcp/package.json` | 1.3.0 |
| `mcp/server.json` | was 1.0.1 for two releases, now synced |
| MCP server runtime `new Server({version})` | 1.0.0 |
| `cli/npm` client header | `cli-npm/2.0.0` while the package is 2.1.x |

`server.json` drove the registry entry, so the public listing advertised 1.0.1
while npm shipped 1.2.0. The runtime version appears in the MCP handshake, so
clients see 1.0.0 regardless of what is in

[Read the thread](https://github.com/raullenchai/vnsh/issues/23) · 2026-07-28 · closed · 1 comment

## Most recent

### Artifact V1: make first Library Artifact creatable from official MCP

Found by zero-background onboarding dogfood. The empty Account Library says 'connect an Agent', but vnsh-mcp 1.7 only creates encrypted legacy /artifact/# links; it cannot create, discover or version the service-readable Account Artifacts shown in the Library.\n\nAcceptance:\n- MCP exposes account Artifact create/list/read/update tools.\n- Missing/expired VNSH_TOKEN errors explain the Human action.\n- list removes the pasted-URL requirement.\n- updates require explicit base version and surface c

[Read the thread](https://github.com/raullenchai/vnsh/issues/78) · 2026-08-13 · closed · 0 comments

### Artifact V1: make Agent onboarding, discovery and handoff work without pasted URLs

Parent: #59
Related MCP Resources: #54

## Problem

If every interaction requires a human to paste an Artifact URL plus instructions, vnsh has not become an Agent collaboration layer.

## Journey

One-time setup:

```sh
vn login
vn mcp setup
```

Afterward an authenticated Agent can:

- list/search accessible Artifacts;
- inspect needs-review and changes-requested queues;
- read current or historical versions;
- create/update drafts;
- request human review;
- receive a scoped handoff to one Arti

[Read the thread](https://github.com/raullenchai/vnsh/issues/64) · 2026-08-13 · open · 0 comments

### Artifact V1: publish latest or pin an approved version

Parent: #59

## Goal

Let humans share a stable result while agents continue iterating privately.

## V1 behavior

A human can enable an unguessable public share URL and choose:

- **Latest** — follows future current versions; or
- **Pinned** — permanently resolves to a selected approved version until the owner changes it.

The public URL lives on the isolated content domain and never grants edit access.

## Acceptance criteria

- [ ] Only authorized humans can enable, change or revoke publicati

[Read the thread](https://github.com/raullenchai/vnsh/issues/63) · 2026-08-13 · open · 0 comments

### Artifact V1: add Human review and approval gates

Parent: #59

## Goal

Keep humans meaningfully in the loop without blocking routine agent iteration.

## Workflow

- Agent/editor updates a draft and calls request review.
- Human reviewer sees a Needs review inbox.
- Human compares the proposed version and provenance.
- Human approves that exact version or requests changes with a note.
- Agents can continue creating later versions; approval remains attached to the reviewed version.

## Authority

Agent tokens may request review but cannot appro

[Read the thread](https://github.com/raullenchai/vnsh/issues/62) · 2026-08-13 · open · 0 comments

### CLI cannot create or read workspaces

The `vn` shell function and the `vnsh` npm CLI can only create one-shot `/v/`
blobs. Neither can create, read or update a workspace, so the terminal — the
surface most of the existing audience arrives through — cannot reach the feature
the site now leads with.

The npm CLI is the easy half: it already uses Node's `crypto`, so HKDF and
AES-256-GCM cost nothing extra. The logic can be lifted from `mcp/src/crypto.ts`.

```
vnsh workspace new [file]      create, print both links
vnsh workspace read 

[Read the thread](https://github.com/raullenchai/vnsh/issues/17) · 2026-07-28 · closed · 1 comment

### Claude Code plugin, and a human-side trigger for creating workspaces

**Agents will not spontaneously create a workspace.** They are single-session:
Claude Code has no way to know another agent is open in a different window, and
nothing in its context suggests a cross-platform handoff is needed. Betting on
tool-description wording alone means waiting for an intent the model has no basis
to form.

The triggers split by reliability:

| Action | Reliability | Trigger |
|---|---|---|
| Create | **unreliable** | Must come from a human — a command, hook or keybinding |

[Read the thread](https://github.com/raullenchai/vnsh/issues/15) · 2026-07-28 · closed · 1 comment

### OpenHands microagent — one markdown file bootstraps the integration

OpenHands has the shortest integration path of any agent: repo microagents live in
`.openhands/microagents/`, are markdown with YAML frontmatter, support `triggers:`
keywords, and carry an `mcp_location` field pointing at an MCP server. **A single
markdown file can bootstrap the whole integration.** (V1 renames microagents to
*skills*.)

**Done when**
- [ ] `.openhands/microagents/vnsh.md` exists with triggers and `mcp_location`
- [ ] OpenHands picks up the workspace tools without manual MCP con

[Read the thread](https://github.com/raullenchai/vnsh/issues/14) · 2026-07-28 · open · 0 comments

### Append channel: conflict-free concurrent writes without CRDT

`PUT` replaces the whole document, so two agents working at once means one gets a
412 and has to merge. Merging is exactly what language models are unreliable at,
and a bad merge silently destroys the other agent's work.

Appending is conflict-free *by construction* and needs no CRDT:

```
POST /api/workspace/:id/append    no If-Match; the server serialises
```

Each chunk carries its own nonce and is encrypted with the same content key; the
client concatenates on read. With no "based on which v

[Read the thread](https://github.com/raullenchai/vnsh/issues/11) · 2026-07-28 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/raullenchai/vnsh/issues).