# Reported issues for dossier

Pod holds 18 of 49 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 [dossier](/mcp/dossier).

## Most discussed

### docs: link plan-artifact, core-api, capabilities references from root README

## Context
The root README's Reference row links only Protocol, Specification, Schema, and the JSON schema. Three reference docs exist but are unreachable from the README: `docs/reference/plan-artifact.md` (plan:v1 artifacts), `docs/reference/core-api.md`, and `docs/reference/capabilities.md` (capability manifest + `cap` command).

## Scope
- One file: `README.md` (the Reference table row)

## Requirements / Acceptance Criteria
- [ ] The Reference row links Plan Artifacts, Core API, and Capabili

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/488) · 2026-08-29 · open · outside contributor · 3 comments

### docs: list @ai-dossier/sched among published packages in docs/contributing/workflows.md

## Context
`docs/contributing/workflows.md` "Publish Packages Workflow" motivation says the workflow automates publishing `@ai-dossier/core`, `@ai-dossier/cli`, `@ai-dossier/mcp-server`, and `@ai-dossier/worktree-pool` — but `@ai-dossier/sched` is also published to npm (see its README badge) and is missing from the list.

## Scope
- One file: `docs/contributing/workflows.md`

## Requirements / Acceptance Criteria
- [ ] The published-packages enumeration in the Publish Packages Workflow section i

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/487) · 2026-08-29 · open · outside contributor · 3 comments

### Trust-check bug: checkSignature() never matches PEM-format Ed25519 keys against trusted-keys.txt

## Bug

`checkSignature()` in `cli/src/verify-dossier.ts` decides whether a signer is trusted by comparing `signature.public_key` against entries in `~/.dossier/trusted-keys.txt`:

```ts
const isTrusted =
  (signature.key_id != null && trustedKeys.has(signature.key_id)) ||
  (signature.public_key != null && trustedKeys.has(signature.public_key));
```

For Ed25519 signatures, `Ed25519Signer` (`packages/core/src/signers/ed25519.ts`) stores `public_key` as the **full PEM block** (`-----BEGIN PUBLIC

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/426) · 2026-08-04 · closed · outside contributor · 3 comments

### Review: Documentation findings from fix/235-documentation-findings-auth-and-publish

## Documentation findings from PR #282

### 1. registry-api-design.md still references NAMESPACE_FORBIDDEN and VERSION_EXISTS (Medium)
- **File:** `registry/docs/planning/registry-api-design.md` lines 307, 537, 539
- These error codes were fixed in auth-and-publish.md but not in registry-api-design.md
- `NAMESPACE_FORBIDDEN` should be `FORBIDDEN`, and `VERSION_EXISTS` should be noted as planned/future

### 2. Frontmatter format inconsistency across docs (Medium)
- auth-and-publish.md and registr

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/286) · 2026-03-06 · closed · outside contributor · 2 comments

### Review: Supportability findings from docs/226-documentation-findings-multi-registry

## Supportability findings from automated review of #226

The multi-registry documentation additions lack troubleshooting guidance. Found during automated review of #270.

### Findings

1. **No error scenarios for invalid registry configuration** (HIGH)
   - `cli/README.md` Registry Configuration section
   - Missing: what happens with unreachable URLs, malformed JSON, wrong registry names

2. **Missing authentication failure scenarios** (HIGH)
   - `docs/getting-started/installation.md` Authent

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/273) · 2026-03-06 · closed · outside contributor · 4 comments

### Review: Security findings from fix/225-docs-cors-security-findings

From automated review of #266.

## Findings

### 1. Case-insensitive origin bypass (High)
- `registry/lib/cors.ts:21,44`
- `Array.includes()` performs case-sensitive matching, but HTTP `Origin` headers and domain names are case-insensitive (RFC 7230, RFC 1035)
- An attacker could bypass the allowlist with `Origin: https://DOSSIER.IMBOARD.AI`
- **Fix**: Normalize both request origin and allowlist entries to lowercase before comparison

### 2. Trailing slash / port number bypass (Medium)
- `regist

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/267) · 2026-03-06 · closed · outside contributor · 2 comments

### Review: Documentation findings from fix/174-maintainability-findings

## Documentation Review Findings

From PR #200 (fix/174-maintainability-findings).

### 1. Missing CONTENT_ORG/CONTENT_REPO env vars documentation (Medium)
- **File**: `registry/docs/planning/auth-and-publish.md` lines 148-157
- `config.ts` now supports `CONTENT_ORG` and `CONTENT_REPO` environment variables with defaults, but these are not documented in the environment variables table
- **Suggested**: Add to env vars table:
  ```
  | CONTENT_ORG  | GitHub org owning the content repo (optional, d

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/207) · 2026-03-06 · closed · outside contributor · 2 comments

### Debugging & Dry-Run Mode

## Summary
Add dry-run mode to preview dossier actions without execution, with risk scoring and detailed impact analysis.

## Business Motivation
Users are cautious about running automation they don't fully understand. Dry-run shows what would happen without executing - building confidence and catching issues early.

## User Impact
- Can't preview dossier actions safely
- Trial and error on real systems
- Slows iteration and experimentation

## Acceptance Criteria
- [ ] `--dry-run` flag for CLI 

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/20) · 2025-11-14 · open · outside contributor · 3 comments

## Most recent

### bug(sched): opencode dispatch template lacks --auto — headless agents die on external_directory auto-rejects (worktree paths)

Found during #471 (sched fleet-parity validation, W3, hcc2).

## Sequence

W3's first opencode dispatch round (openrouter glm) had three agents exit abruptly mid-phase:

- imboard#3433 — died during plan, right after `permission requested: external_directory (/home/yuvaldim/.claude/*, /home/yuvaldim/.config/opencode/*); auto-rejecting` (it ran `cat ~/.claude/mcp.json` to inspect MCP config for the plan-phase prod-data reachability check)
- imboard#3824 — posted plan/done, then in implement its `

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/506) · 2026-08-30 · open · outside contributor · 0 comments

### feat: Deterministic TypeScript markdown security scanner in core

## Summary

Implement a deterministic TypeScript security scanner in `packages/core/` that mirrors the AI-driven scanning methodology defined in the `scan-markdown-security` dossier (`main/examples/security/scan-markdown-security.ds.md`). This provides programmatic, repeatable analysis without requiring an LLM.

## Motivation

The dossier-based scanner relies on an AI agent to perform pattern matching. A deterministic TypeScript implementation enables:
- **CI/CD integration** — scan on every com

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/366) · 2026-03-07 · closed · outside contributor · 0 comments

### fix: config-cmd.ts help text describes DOSSIER_REGISTRY_TOKEN incorrectly

**Source**: PR #305, found during review of fix/215-doc-findings-security-registry-config
**File**: cli/src/commands/config-cmd.ts:34
**Issue**: Help text says "Auth token for the default registry" but the token actually creates credentials for the virtual "env" registry, not the default registry.
**Why escalated**: This is a code change to CLI help text, not a documentation file. Out of scope for the docs-only issue #215.

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/306) · 2026-03-06 · closed · outside contributor · 0 comments

### dx: add "ai-dossier doctor" diagnostic command

## Problem

No diagnostic tool when setup fails. Common issues: MCP not configured, wrong Node version, hook not installed, registry unreachable. We need a safety net for our multi-component setup.

## Solution

New `ai-dossier doctor` command checking:

- [ ] Node.js version (≥20)
- [ ] CLI / core / MCP server versions
- [ ] `~/.dossier/` directory and config exist
- [ ] Claude Code settings: hook installed, MCP configured
- [ ] Registry reachability and auth status
- [ ] Clear pass/fail with a

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/294) · 2026-03-06 · closed · outside contributor · 0 comments

### docs: complete onboarding tutorial suite

## Problem

Only 1/5 tutorials completed. 4 are "coming soon". Current tutorial requires many manual steps before user sees value.

## Supersedes

- #12 (Interactive Quickstart Tutorial)
- #13 (2-Minute Demo Video)

Consolidated with concrete deliverables.

## Solution

Create 3 new tutorials:

1. **"MCP in 60 Seconds"** — single command install, ask Claude to list/run dossiers (the critical missing piece)
2. **"Author and Publish"** — create → validate → sign → publish → run lifecycle
3. **"Rec

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/293) · 2026-03-06 · closed · outside contributor · 0 comments

### docs: replace "Try it Now" section with progressive-friction setup

## Problem

README "Try it Now" recommends MCP (Option A) but shows the *hardest* path (manual JSON editing). The simpler `claude mcp add` one-liner from mcp-server/README.md is not mentioned. Option B requires `git clone`.

## Solution

Restructure to lowest-friction-first:

- **Option A**: `claude mcp add dossier --scope user -- npx @ai-dossier/mcp-server` (one command)
- **Option B**: `npx @ai-dossier/cli verify <raw-github-url>` (no clone needed)
- **Option C**: Copy-paste into any LLM (upgr

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/292) · 2026-03-06 · closed · outside contributor · 0 comments

### dx: make "ai-dossier init" configure Claude Code MCP server automatically

## Problem

`ai-dossier init` creates `~/.dossier/` and installs the discovery hook but does NOT configure the MCP server. Users must separately edit JSON or know `claude mcp add`. Two disconnected steps.

## Solution

Enhance `init` to:

- [ ] Auto-detect `claude` CLI on PATH → run `claude mcp add dossier --scope user -- npx @ai-dossier/mcp-server`
- [ ] Fall back to writing JSON config if `claude` not found
- [ ] Add `--skip-mcp` / `--with-mcp` flags
- [ ] Interactive prompt when TTY detected

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/291) · 2026-03-06 · closed · outside contributor · 0 comments

### feat: submit to Claude Code Plugin Marketplace

## Problem

Our MCP server works but requires manual JSON config editing or knowing `claude mcp add`. It's not discoverable from within Claude Code. Projects like token-optimizer use `/plugin marketplace add` for single-command install with auto-updates.

## Solution

- [ ] Create `.claude-plugin/plugin.json` + `.mcp.json` at repo root
- [ ] Submit to Anthropic's official Plugin Marketplace (platform.claude.com/plugins/submit)
- [ ] List on third-party registries (mcp.so, mcpmarket.com)
- [ ] Up

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/289) · 2026-03-06 · closed · outside contributor · 1 comment

### Review: Documentation findings from feat/216-external-reference-declaration

## Documentation gaps identified in review of #216

### 1. docs/reference/schema.md — Missing external reference fields
The schema reference doc does not document `content_scope` and `external_references` fields.

### 2. docs/guides/dossier-guide.md — Missing from schema overview
The guide mentions security fields but doesn't cover external references.

### 3. mcp-server/README.md — read_dossier tool description
Doesn't mention `security_notices` output for undeclared external URLs.

### 4. Root

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/261) · 2026-03-06 · closed · outside contributor · 2 comments

### Review: Documentation findings from fix/179-supportability-findings-manifest

## Documentation findings from automated review of PR #217

### 1. MVP0 implementation docs lack error response documentation (Low)
- **File:** `registry/docs/planning/mvp0-implementation.md`
- The API endpoint documentation doesn't describe potential error responses from manifest fetch
- Should document HTTP 500 responses, network timeouts, malformed manifest JSON scenarios

### 2. Registry README API table missing error documentation (Low)
- **File:** `registry/README.md`
- The API endpoints t

[Read the thread](https://github.com/imboard-ai/ai-dossier/issues/221) · 2026-03-06 · closed · outside contributor · 2 comments

The remaining reports are on [the project's issue tracker](https://github.com/imboard-ai/ai-dossier/issues).