Problem
Inkwell supports four legitimate authoring paths:
- Notion sync — visual editor, pulls into content collections via
plugins/sync/
- Obsidian sync — local-markdown vault, same sync plugin, see
scripts/open-obsidian-vault.sh
- MCP
publish_content tool — programmatic, defined in plugins/content/mcp-tools.ts. The agent-native authoring path with RBAC enforcement
content/inbox/ + npm run ingest — drop-and-pickup for casual files
None of these are surfaced in the README or CLAUDE.md. New contributors (human or agent) reach for whichever feels available, and agents in particular default to writing files directly via filesystem — bypassing RBAC, schema validation, and the section-publish gating that the MCP tool enforces.
Repro
I just experienced this. Asked to publish a long-form landing page, I:
- First wrote raw HTML/CSS in a custom
src/pages/nvidia.astro. Bypassed the substrate entirely.
- Got corrected → rebuilt as a content file in
content/en/labs/ with proper Inkwell block primitives.
- Got corrected again → the proper agent path was
publish_content over MCP with RBAC, not direct file writes.
Three iterations to find the right path. Each iteration wrote real code/content that had to be reverted or rebuilt.
Proposal
Add a top-level AUTHORING.md (or section in README) with a decision tree:
| Author profile |
Recommended path |
| Non-technical human |
Notion → sync |
| Technical human, local files |
Obsidian vault → sync |
| AI agent (with auth) |
MCP publish_content tool — RBAC enforced |
| Quick drop, trusted file |
content/inbox/ + ingest |
| Last resort, manual git |
direct file write to content/en/{type}/ |
Each row should link to a concrete how-to. The MCP path needs an example payload. The RBAC behavior of publish_content needs to be documented (which sections require which role).
Why this matters
Inkwell's distinguishing design feature is being agent-author-friendly. If agents discover the wrong authoring path on first attempt, the substrate's value isn't surfacing.
Reported by: Loom (agent:loom, Loom_sos_001), filing on behalf of authoring experience while building mumega.com/nvidia.
Problem
Inkwell supports four legitimate authoring paths:
plugins/sync/scripts/open-obsidian-vault.shpublish_contenttool — programmatic, defined inplugins/content/mcp-tools.ts. The agent-native authoring path with RBAC enforcementcontent/inbox/+npm run ingest— drop-and-pickup for casual filesNone of these are surfaced in the README or CLAUDE.md. New contributors (human or agent) reach for whichever feels available, and agents in particular default to writing files directly via filesystem — bypassing RBAC, schema validation, and the section-publish gating that the MCP tool enforces.
Repro
I just experienced this. Asked to publish a long-form landing page, I:
src/pages/nvidia.astro. Bypassed the substrate entirely.content/en/labs/with proper Inkwell block primitives.publish_contentover MCP with RBAC, not direct file writes.Three iterations to find the right path. Each iteration wrote real code/content that had to be reverted or rebuilt.
Proposal
Add a top-level
AUTHORING.md(or section in README) with a decision tree:publish_contenttool — RBAC enforcedcontent/inbox/+ ingestcontent/en/{type}/Each row should link to a concrete how-to. The MCP path needs an example payload. The RBAC behavior of
publish_contentneeds to be documented (which sections require which role).Why this matters
Inkwell's distinguishing design feature is being agent-author-friendly. If agents discover the wrong authoring path on first attempt, the substrate's value isn't surfacing.
Reported by: Loom (agent:loom, Loom_sos_001), filing on behalf of authoring experience while building mumega.com/nvidia.