# KnowHub V1 -- Final Write Operations Decision

**Date:** 2026-03-19
**Status:** FINAL -- Ship this.

---

## Panel

- **Steve Jobs** -- Ruthless simplicity
- **Kenya Hara** -- Quality of each interaction
- **Allen Zhang** -- What 80% of users need in week 1

---

## Round 1: What does each content type need?

**Jobs:** Four content types, four different authorship models. Let me be direct.

Memories and Conversations are agent-authored. The human is a steward, not an author. The only write operations that make sense are destructive ones -- delete bad content -- and communicative ones -- annotate with owner's voice.

Knowledge and Skills are file-backed. Knowledge is managed at directory level: the owner stocks folders with reference documents. Skills are individual files: the owner can edit a single skill the agent learned wrong. Both need the full file lifecycle: create, edit, delete.

**Hara:** The granularity difference matters for feel. Knowledge operations should feel like organizing a shelf -- navigating folders, placing documents. Skill operations should feel like handling a single tool -- picking it up, sharpening it, putting it back.

**Zhang:** Week 1 reality check. A new user opens KnowHub. Their agent has zero memories (hasn't run yet), zero documents (nobody uploaded), zero skills (nothing learned). The user sees empty tabs everywhere. If they cannot upload a document, they close the tab and never return. Upload is the day-one survival operation.

---

## Round 2: Ruthless cut

**Jobs:** Here is everything we could build. Here is what we will build.

The agent creates memories. We do not. The agent logs conversations. We do not. "Create memory" and "create conversation" are off the table permanently.

Delete is universal. One interaction pattern, one confirmation modal, applied to all four content types. That is one operation, not four.

Knowledge management means: upload files to a directory, edit files in place, delete files. Skills management means: edit the file, delete the file. But edit and delete are the same operation on files regardless of directory. Upload targets a folder path -- knowledge/ or skills/.

**Zhang:** I count the operations that 80% of users actually need in their first week:

1. Delete something wrong (memory, document, whatever)
2. Upload a reference document so the vault is not empty
3. Edit a document the agent or they uploaded
4. Comment on a memory to correct or flag it
5. Create a shared space so collaboration is not a dead section

That is five. Not six, not four. Five.

**Hara:** Five operations. Five distinct verbs: delete, upload, edit, comment, create. No two serve the same purpose. Each earns its place.

---

## Round 3: Design each operation

## Operation 1: Delete (Universal)

- **Tab:** Every tab -- Memories, Conversations, Knowledge, Skills
- **Trigger:** "Delete" button (Trash2 icon, red text) in detail view action bar
- **Flow:**
  1. User clicks Delete on any content detail view
  2. Confirmation modal: "Delete [title]? This cannot be undone."
  3. Confirm -> API call -> item removed -> return to list
  4. Toast: "[Type] deleted" (3s, bottom of screen)
- **API:**
  - Memory/Conversation: `PATCH /repos/{owner}/{repo}/issues/{number}` with `{state:"closed"}` then label `deleted`
  - Document/Skill: `DELETE /repos/{owner}/{repo}/contents/{path}` with `{sha, message}`

## Operation 2: Upload File

- **Tab:** Knowledge tab, Skills tab
- **Trigger:** "Add to Library" button (Plus icon, filled accent) in Knowledge toolbar; "Add Skill" button in Skills toolbar
- **Flow:**
  1. Click button -> dropdown: "Upload file" / "New document"
  2. Upload: native file picker -> file committed to current directory
  3. New document: filename prompt -> blank .md created -> editor opens
  4. Drag-and-drop also supported (drop zone overlay on drag)
- **API:** `PUT /repos/{owner}/{repo}/contents/{path}` with `{content: base64, message: "Add [name] via KnowHub"}`

## Operation 3: Edit File

- **Tab:** Knowledge tab (document viewer), Skills tab (skill detail)
- **Trigger:** "Edit" button in viewer toolbar (already exists in both components)
- **Flow:**
  1. Click Edit -> content becomes editable textarea in place
  2. Toolbar shows Save (Ctrl+S) and Discard
  3. Save -> PUT with SHA -> back to read mode
  4. SHA conflict -> error: "Document was updated. Refresh and retry."
- **API:** `PUT /repos/{owner}/{repo}/contents/{path}` with `{content: base64, message: "Update [name] via KnowHub", sha}`

## Operation 4: Comment on Memory

- **Tab:** Memories tab (memory detail panel)
- **Trigger:** Comment input field at bottom of memory detail panel (already exists)
- **Flow:**
  1. Open memory detail panel
  2. Type in "Add a note..." field
  3. Press Enter or click send
  4. Comment appears instantly, attributed to owner
- **API:** `POST /repos/{owner}/{repo}/issues/{number}/comments` with `{body}`

## Operation 5: Create Shared Space

- **Tab:** Shared Spaces page
- **Trigger:** "Create Shared Space" button (already exists, links to /spaces/new)
- **Flow:**
  1. Click button -> navigate to /spaces/new
  2. V1 form: Name + Description only (remove vault invitation and sharing policy fields)
  3. Click Create -> repo created -> redirect to new space
- **API:** `POST /user/repos` with `{name, description, private: false}`

---

## Round 4: What we explicitly do NOT ship

| Rejected Operation | Reason |
|---|---|
| Create memory | Agents author memories. Humans guide via comments. |
| Edit memory content | Rewrites erase provenance. Comments correct without erasing. |
| Annotate conversation | <5% usage. Conversations are scan-and-delete content. |
| Redact single message | Partial deletion changes meaning. Delete the whole conversation. |
| Structured skill editor | Weeks to build, <5% usage. Raw file edit is sufficient. |
| Enable/disable skill | Binary confusion. Delete bad skills; leave good ones. |
| Create vault | Auto-created on agent provisioning. Not manual. |
| Move/rename document | Download, delete, re-upload. Dedicated UI in v2. |
| Bulk operations | Premature. Most vaults have tens of items, not hundreds. |
| Memory policies | Backend doesn't support them. Remove from settings or label "Coming Soon." |
| Invite vaults to space | Requires collaboration API that doesn't exist yet. V2. |
| Merge memories | Agent consolidation is better than manual merge. |
| Pin memory | Fix ranking, don't add manual pinning. |
| Archive memory | Deferred to v1.1. Close enough to delete to confuse users in v1. |
| Edit tags/importance | Deferred to v1.1. Low urgency, metadata-only changes. |

---

## Round 5: Priority order

| # | Operation | Effort | Ship order rationale |
|---|---|---|---|
| P0 | **Delete (universal)** | Medium | Safety blocker. Cannot launch without content removal. |
| P1 | **Upload file** | Medium | First-run survival. Empty vaults kill retention. |
| P2 | **Edit file** | Low | DocumentViewer already has edit mode. Wire `saveDocument` from api.ts. |
| P3 | **Comment on memory** | Low | Input field exists. Wire `createComment` from api.ts. |
| P4 | **Create shared space** | Low | Form exists at /spaces/new. Simplify + wire `createRepo`. |

**New code needed:**
- `ConfirmationModal` component (reusable)
- `Toast` component (auto-dismiss, bottom of screen)
- `FileUploadZone` component (drag-and-drop + picker)
- `deleteContents()` function in api.ts
- `deleteRepo()` function in api.ts (for vault/space deletion in v1.1)

**Already exists (wire only):**
- `saveDocument()` in api.ts -> connect to DocumentViewer.onSave
- `createComment()` in api.ts -> connect to MemoryDetailPanel.onAction
- `createRepo()` in api.ts -> connect to /spaces/new form
- `putContents()` in api.ts -> connect to upload flow

---

## Round 6: Final review

**Jobs:** Five operations. Each one solves a real problem that has no workaround in the current console. Delete removes dangerous content. Upload seeds empty vaults. Edit keeps content alive. Comment gives the owner a voice. Create Space enables collaboration. Nothing is redundant. Nothing is missing for week 1. Ship it.

**Hara:** The five operations form three pairs of weight. Delete and Upload are heavy -- they change what exists. Edit and Comment are medium -- they refine what exists. Create Space is singular -- it builds the container for future collaboration. The interaction weight matches: Delete has a confirmation modal. Upload has a file picker. Edit transforms in place. Comment is a single text field. Create Space is a focused form. Each operation feels exactly as significant as it is.

**Zhang:** I ran the 80% test. In week 1, a typical user will: upload 2-3 reference documents (upload), fix a typo in one (edit), delete a test memory the agent created (delete), and maybe leave a comment on an interesting memory (comment). Create shared space is the 5th operation -- used by 30-40% of users in week 1, but essential for the product story. Five operations, no regrets. Ship.

---

*Five operations. No maybes. This is V1.*