arkon-edit: Edit the Knowledge Base

Always read the current page before proposing changes. Always confirm with the user before submitting.

---

Permission Tiers

Role	Tool to use	Review required
Contributor	propose_wiki_edit	Yes — goes to editor queue
Editor	edit_wiki_page	No — writes directly
Admin	edit_wiki_page	No — writes directly

If you try edit_wiki_page and get a permission error, fall back to propose_wiki_edit.

---

Workflow: Propose an Edit (Contributor)

1. Find the page — search_wiki(query) or read_wiki_index() to locate the slug.
2. Read current content — read_wiki_page(slug). Never propose without reading first.
3. Draft the edit — produce the full updated Markdown (not a diff — the tool takes full content).
4. Confirm with user — show the diff or summary of changes. Get explicit approval.
5. Submit — propose_wiki_edit(slug, content_md, note="one-line explanation").
6. Report the draft ID to the user so they can track it.

Do not submit a draft without user confirmation. The note field is important — editors need context.

---

Workflow: Direct Edit (Editor/Admin)

Same steps 1-4 above, then:

5. Submit — edit_wiki_page(slug, content_md, change_note="one-line explanation").
6. Report the new version number returned.

---

Content Rules

• Submit full page content — these tools replace, not patch.
• Max 50,000 characters per submission.
• Cannot edit reserved pages: _index, _log.
• Preserve existing wikilinks [[slug]] unless intentionally removing them.
• Keep the page's existing frontmatter fields (title, type, knowledge_type_slugs, etc.) unless the change specifically needs to update them.

---

When NOT to edit

• Do not edit without user instruction — even if you spot an error while querying.
• Do not create new pages via these tools (they only update existing pages).
• If the target slug doesn't exist, tell the user — new page creation is an admin/pipeline operation.

---

Iteration loop: when a reviewer sends changes back

If a reviewer used request_changes_on_draft, the draft moves to status needs_revision. The original draft is preserved; you (or the user) can fix it without creating a fresh proposal.

1. read_wiki_page(slug) — make sure the page hasn't moved on while you waited.
2. Read the reviewer note attached to the draft (visible in the in-app notification). Address every point they raised.
3. Confirm the rewrite with the user.
4. resubmit_draft(draft_id, content_md, note="what I changed in this round").
   • Bumps revision_round and notifies reviewers.
   • The prior submission is snapshotted to history (rounds) so the reviewer can diff your changes against the previous round.

Withdrawing your own draft

If you no longer want a pending or needs_revision draft to be reviewed:

withdraw_draft(draft_id)

Only the original author may withdraw (admins can override via the REST API). Withdrawn drafts are terminal and disappear from reviewer queues. Confirm with the user before withdrawing — it cannot be reversed via MCP.

Scope disambiguation

When propose_wiki_edit or edit_wiki_page finds the same slug in multiple scopes (global + project, for example), the call fails with a list of the candidate scopes. Re-call with scope_type and scope_id to target the specific page the user means.

---

Creating a brand-new page

First check whether one already exists. Always run search_wiki(query) and inspect the top hits before proposing a new page — duplicates waste reviewer time and trigger the AI duplicate check.

Role	Tool	What happens
Contributor+	propose_wiki_create	Draft enters reviewer queue; page materialised on approve
Editor+ (workspace) or wiki:write:all (global)	create_wiki_page	Page created immediately

Required fields for both tools:

• slug — unique inside the chosen scope, no whitespace, not _index/_log
• title — display title
• content_md — full Markdown
• page_type — one of entity | concept | source | topic
• scope_type — global | department | project (with scope_id for the latter two)
• knowledge_type_slugs — taxonomy tags that drive RBAC visibility; ask the user which categories apply rather than guessing

Workflow:

1. search_wiki to confirm nothing similar exists.
2. Show the user the suggested slug, page_type, knowledge_type_slugs, scope and the full content. Confirm.
3. Call the appropriate tool. Report the returned draft ID (propose path) or the created page version (direct path).

If approve later returns a slug conflict, the reviewer or the contributor must override final_slug (reviewer side) or rename and resubmit (contributor side).

---

AI pre-review

Every draft you submit is annotated by an AI pre-review layer that flags:

• PII / secrets (emails, phone numbers, API keys, JWTs, ...)
• Broken wikilinks to slugs that don't exist
• Possible duplicates with existing pages (embedding similarity)
• Tone / scope fit / factual concerns (LLM judgment)

The flags are advisory only — they do not block submission and reviewers make the final call. But: address obvious ones (broken links, accidental PII) before submitting to save the reviewer time.

If a regex flags a legitimate contact email or hotline that you intentionally included in the page, add a suppression comment on the line above:

<!-- pii-allow: contact-email -->
Email team: compliance@example.com

The marker covers regex matches on the same or next non-blank line. Choose a short, honest reason — it shows up in the reviewer's audit trail.