Skip to content

feat(knowledge): upload project documents from the web into .kortix/knowledge - #4

Draft
andokivilaid wants to merge 8 commits into
mainfrom
knowledge-upload
Draft

feat(knowledge): upload project documents from the web into .kortix/knowledge#4
andokivilaid wants to merge 8 commits into
mainfrom
knowledge-upload

Conversation

@andokivilaid

@andokivilaid andokivilaid commented Sep 24, 2026

Copy link
Copy Markdown
Owner

Users can now add documents to a project's knowledge from the web, without starting a session. Inspired by manav1125/mira-ai's knowledge base, rebuilt git-native: no new DB tables, and no prompt injection. The project repo stays the single source of truth.

Changes

  • API: GET/POST/PATCH/DELETE /v1/projects/:id/knowledge and GET …/knowledge/file.
    • Multipart upload. PATCH moves or re-describes a file. The download ETag is the git blob id.
    • Permissions: project.file.read / project.file.write.
    • Direct commit to the default branch, the same as agent config and triggers. The documents and the regenerated .kortix/knowledge/INDEX.md land in one commit. A moved branch tip triggers a re-plan, up to 3 times.
    • Binary-safe: commitMultipleFilesToBranch now accepts raw bytes.
    • Limits: 25 MiB/file, 10 files and 50 MiB per upload, 200 MiB per project.
    • Traversal, hidden names and the root INDEX.md return 400.
  • SDK: kortix.project(id).knowledge (list/upload/update/delete/download) and qk.project.knowledge. Added with TDD; the surface snapshots only gained names.
  • Web: Customize → Knowledge tab and a command-palette entry.
    • Drag-and-drop upload with optional folder, description and replace.
    • A list with type, size and description, plus download, edit and delete.
    • Strings in all 9 locales.
  • Agents: a managed kortix-knowledge skill. It reads INDEX.md, converts office/PDF with anydoc, and lands its own additions through a change request.
  • Docs: a project knowledge page.

Verification

  • API tests: 34 pass / 0 fail, including a byte-exact binary round trip against a real bare repo.
  • pnpm test -- --domain knowledge: KNOW-1 and KNOW-2 pass (16 steps, 72 assertions), including negative paths (traversal, oversize, a member without write permission).
  • Full pnpm test: exit 0, 439/439 flows. Route coverage: 0 uncovered.
  • SDK: 3674 pass / 0 fail, smoke:install passed.
  • Web:
    • tsc: known pre-existing errors only.
    • eslint: clean.
    • Brand audit.sh: clean.
    • i18n audit: 0 findings.
  • Chromium on the local stack:
    • uploaded a real PDF and a .md;
    • asserted the multipart payload and the 201 response with a commit id;
    • listed both files; the downloaded PDF was byte-identical;
    • delete returned 200.

Not verified

  • A managed or GitHub-backed repo; only local bare repos were used.
  • An agent in a real cloud sandbox reading INDEX.md through the skill.
  • The Electron desktop app.

🤖 Generated with Claude Code

andokivilaid and others added 8 commits September 24, 2026 11:12
@andokivilaid @claude
feat(api): upload project knowledge documents into the repository
63e97d8 
Add /v1/projects/:projectId/knowledge (GET list, POST multipart upload,
PATCH move/describe, DELETE) and /knowledge/file (byte-exact download,
ETag = git blob id). Documents commit under .kortix/knowledge/ with a
regenerated INDEX.md in the same commit, directly on the default branch,
like the dashboard's other repository editors. Reads gate on
project.file.read, writes on project.file.write.

Every write is a compare-and-swap on the branch tip (force-with-lease via
expectedFileRevision on INDEX.md) with up to 3 re-plans, so concurrent
writers never drop an index entry. commitMultipleFilesToBranch now takes
Uint8Array content so binary files commit verbatim.

Limits: 25 MiB per file, 10 files / 50 MiB per request, 200 MiB per
project. Paths are validated: no traversal, hidden segments, link-breaking
characters, or the reserved root INDEX.md.

Flows KNOW-1 (lifecycle + read-back through /files and /files/content)
and KNOW-2 (traversal, oversize, member/non-member/anonymous refusals).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
feat(sdk): add project(id).knowledge for knowledge documents
19488ab 
Additive surface over /v1/projects/:projectId/knowledge:
listProjectKnowledge, uploadProjectKnowledge (multipart, one or many
Files, folder/description/replace), updateProjectKnowledgeFile (move and
describe), deleteProjectKnowledgeFile, downloadProjectKnowledgeFile
(exact bytes as a Blob), plus their types. The facade binds them as
kortix.project(id).knowledge.{list,upload,update,remove,download}.

Public surface snapshots re-recorded: additions only, no removals.
Reference docs and README list the new namespace.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
feat(starter): add the managed kortix-knowledge skill
ccf570a 
Tells agents that project documents live in .kortix/knowledge/ with an
INDEX.md (one line per file), to read the index when a task may need
project documents, to convert office files and PDFs with anydoc /
convert-documents-to-markdown, and how to add a document themselves
(file + index line, landed through a change request).

Registered in KORTIX_MANAGED_SKILL_NAMES so the sandbox bake, the API
skills catalog, and `kortix system-skills` serve it. kortix-system lists
it beside kortix-memory. Embedded starter snapshot regenerated.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
feat(sdk): add qk.project.knowledge query key
c3ac45a 
Project-scoped cache key for listProjectKnowledge, under qk.project.scope
so project-wide invalidation reaches it. Covered by the existing
"every project-scoped key is prefixed by scope" test.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
feat(web): add the Knowledge tab to Customize
d6ce3bc 
/projects/[id]/customize/knowledge lists the documents in
.kortix/knowledge/ (type, size, description, usage against the project
limit) and uploads by drag-and-drop or file picker with an optional
folder, description, and replace flag. Row actions download, edit
(move + description), and delete behind a ConfirmDialog. All data flows
through @kortix/sdk; the selection is pre-checked against the server
limits the list returns.

The tab follows Skills in the capability bar, gated on
project.file.read; write controls appear only with project.file.write.
Command palette entry "Knowledge". New `knowledge` i18n namespace in all
nine catalogs; menu strings added to the generated key map.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
docs: document project knowledge
2b2649d 
New /docs/project/knowledge page: where documents live, the INDEX.md
format, how agents use them through the kortix-knowledge skill, size
limits and why the repository stays small, permissions, and the HTTP and
SDK surface. Linked from the project overview.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
test(knowledge): prove a project member cannot list or download
66ea542 
KNOW-2 now asserts 403 for a project member on GET /knowledge and
GET /knowledge/file as well as on the writes, matching the documented
project.file.read gate.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@andokivilaid @claude
fix(web): keep the upload modal title stable while it closes
5ec3a42 
After a successful upload the selection is cleared before the modal's
exit animation ends, so the title flashed "Upload 0 documents". The
modal now keeps showing the last selection while it animates out.
Found while driving the page in Chromium.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@andokivilaid