Skip to content

PRODUCT.md

Latest commit

 

History

History
212 lines (173 loc) · 11 KB

PRODUCT.md

File metadata and controls

212 lines (173 loc) · 11 KB
Raw

Product

Provenance. The maintainer asked for this file to be written directly instead of through the init interview, so nothing here is an interview answer. Every fact is either sourced to a repository artifact — README, an issue, DESIGN.md, CONTRIBUTING.md, package.json — or marked [inferred], which means it was read out of the code and the direction the repository already states. Confirm or correct the [inferred] items before treating them as settled, and treat the two items under "Undecided" in Capabilities and Constraints as open questions, not as answers.

Platform

web

The shell is Electron, so the interface is drawn by a web engine and this is the only schema value that fits. adaptive is wrong: the design language does not switch per OS. Shipped artifacts are Windows and macOS (Apple Silicon) only, but that is a release-pipeline fact, not a platform fact — see Operating Context.

Users

People who read long documents for study or research and need to be able to trust what they write down: graduate students, researchers, and analysts working from papers, PDFs, slide decks and web pages. [inferred] from "research workspace" in the README and "research/learning workstation" in #65.

Single-user and local by construction: one person, their own machine, a growing body of sources, no account, no sync, no collaboration, no telemetry (README, "What is not here yet").

The job to be done, in the maintainer's own words in #65:

import → read → annotate/cite → ask → inspect the source → jump back → excerpt into a note

Product Purpose

KnowNote turns a person's own documents into a knowledge base they can question, and answers from those documents with a reference back to the passage the answer came from. Parsing, splitting, embedding and vector search run inside the application; the only thing that leaves the machine is the request to the model endpoint the user configured (README).

Success means the loop above closes: the reader can go from an answer to the original page and paragraph and back without leaving the app, and can inspect what an answer was actually built from instead of taking it on faith (#65, #82).

Positioning

A citation resolves to a source location, not to a chunk.

A chunk can be re-split, re-embedded, or replaced by a different retrieval strategy; a citation has to survive all of that. The architecture therefore persists source blocks carrying page, heading level and character span, and has chunks reference block spans rather than the reverse (#82). That is the mechanism a neighbouring product cannot copy by shipping a feature, because it constrains the indexing path itself.

The corollary is written down by the maintainer rather than discovered by a user: in #82, "the README claims … precise source traceability. The claim is ahead of the code", and the indexing path was actively discarding the structure it had already parsed. Do not claim more than the shipped build does.

Operating Context

  • Bring your own model. Any OpenAI-, Anthropic- or Google-compatible endpoint, or a local server such as Ollama. No bundled chat model, no account (README).
  • Offline retrieval is a supported state, not a degraded one. The embedder (Xenova/multilingual-e5-small through ONNX, 384 dimensions, q8, revision pinned, remote loading disabled) downloads once and then runs in the Electron main process (README, Architecture).
  • Storage is SQLite with sqlite-vec through Drizzle ORM; one vector table per notebook, each carrying its own width, so vectors from different embedding spaces are never compared (README; #47).
  • Publication position: unsigned and un-notarised builds, no Linux build, macOS is Apple Silicon only. [inferred] This describes what the release pipeline publishes today, not what the code can build.
  • Two locales ship: English and Simplified Chinese, kept in sync (CONTRIBUTING.md).
  • Work happens against a written interface system. DESIGN.md is declared the single source of truth for UI decisions and is guarded by npm run check:design; the guard runs in CI before the build matrix.

Capabilities and Constraints

Confirmed by the README and the code:

  • Import PDF, Word, PowerPoint and web pages; each format keeps the structure it has — page boundaries, headings, slides.

  • Passage splitting at roughly 500 characters with ~50 characters of overlap, recording start and end offsets in the extracted text.

  • Local embedding and vector retrieval, and chat over retrieved passages.

  • Notes (Tiptap) and mind maps beside the sources; quiz and Anki card surfaces exist and open in their own windows.

  • Protocol-based model connections — OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI — instead of a vendor registry. A model is a connection: protocol + base URL + API key + model ID, with the capability declared explicitly by the user rather than guessed (#44).

  • Structural constraints: Electron with a main/renderer/preload/shared split; native modules (better-sqlite3, sqlite-vec) unpacked from the asar; a deliberately minimal dependencies list, because anything listed there stays a runtime require() and has to be collected into the package (package.json, electron-builder.yml).

  • Process constraints: Conventional Commits for both commits and PR titles, because the prefix selects the label and the release-notes section; a single Verify workflow is the gate; en-US and zh-CN locales move together (CONTRIBUTING.md).

  • A notebook holds one growing conversation. Confirmed by the maintainer. There is no conversation picker and no "new chat": opening a notebook lands you in its ongoing thread, and the store already creates the session on demand. When that thread approaches the model's context budget, SessionAutoSwitchService summarises it, archives the old row and continues in a new one — a rollover, not a second conversation the user has to manage. Because the user experiences one thread, a rollover must never be silent.

  • Every answer records the passages it was built from. Retrieval already knows the documentId, chunkId and passage text; these are now persisted on the assistant message and rendered as quotable evidence, with the retrieval outcome recorded too (used / none / failed). What this does not yet provide is a page or character span: the indexing path computes chunk offsets against a preprocessed string rather than documents.content, and parseResult.structure is still discarded, so a span-accurate citation would be a false claim until #82 lands. Inline per-sentence markers (the [cite:id] contract Cherry Studio and Open Notebook both use) also need a system-prompt change and real model testing, so they are deliberately not in place yet.

Undecided, recorded rather than resolved:

  • The README says quiz generation, audio transcription and slide generation are "in development" and "not in any release", but quiz and Anki surfaces are implemented in the renderer. Which statement is current needs a maintainer answer, and the answer decides whether those surfaces are promoted or hidden.
  • No accessibility standard is named anywhere in the repository. See Accessibility & Inclusion.

Brand Commitments

  • Name: KnowNote. Tagline in use: A local-first research workspace. Sub-line: Research your documents. Trust every answer. Position line: Desktop · Local RAG · Bring your own model · Open source (README).
  • Licence: GPL-3.0. Contributions are licensed under the same terms.
  • Voice: plain, technical, candid about limits. The README spends a section on "What is not here yet", and #82 records the maintainer catching their own claim running ahead of the code. That habit is a commitment, not a style preference: limits are documented in the same voice as features.
  • The website is the long-form positioning. knownote.pages.dev carries the mechanism, the limits, and a comparison with NotebookLM and AnythingLLM. The README points at it as "the full story". [inferred] That copy is not in this repository and must not be re-invented here.
  • No further binding identity. No palette, typeface or mark is declared binding beyond what DESIGN.md defines; src/renderer/src/assets/logo.png and resources/ hold the only brand assets. [inferred]

Evidence on Hand

  • DESIGN.md — the executable interface system, enforced by npm run check:design (scripts/check-design-tokens.mjs).
  • .github/images/screenshot-main.png — the only real screenshot in the repository; the README embeds it as the product preview.
  • test/fixtures/sample.pdf, sample.docx, sample.html — parser fixtures, plus a Node built-in test suite with no added runtime dependency.
  • The issue tracker holds the roadmap: #82 (the v1.4 epic) and its children #65–#80, which the README's "not here yet" section is written against.

Absences that later work must not fill in. There are no customer testimonials, no case studies, no benchmark numbers, no performance claims, no download or user counts, and no pricing. Do not author any of these; if proof is needed, ask for it.

Product Principles

  1. Provenance before fluency. An answer without a resolvable source location is an unverified claim. The citation is the product, not the chat bubble. Today the answer carries the passages it used, and that is the first half of this principle. It becomes the whole of it when a citation resolves to a page and a span rather than to a passage's text (#82).
  2. Local is the default, not a mode. Retrieval has to work with the network off, and the only outbound request is the endpoint the user configured.
  3. Say what is not there. A claim ahead of the code is a bug, and the README is the place that gets corrected — not the roadmap.
  4. The document is the subject. Reading is the anchor and the conversation is an overlay; chrome stays neutral and quiet (#65, DESIGN.md).
  5. Structure is preserved, not normalised. Page boundaries, headings and slide structure survive import, because a citation depends on them.

Accessibility & Inclusion

Enforced today (DESIGN.md, npm run check:design):

  • Every interactive surface defines hover, selected, focus-visible and disabled; missing states are treated as bugs.
  • Both themes must be usable on every page, and colour is never the only carrier of state — pair it with weight, an icon or a border.
  • Focus rings are explicitly part of the state contract rather than an addition.

Required by #65, not yet built:

  • A keyboard-first path to open a citation, return to the chat, and move between the three zones, reusing ShortcutManager + useShortcutExecutor.

Undecided:

  • No target standard is named — WCAG 2.2 AA, or anything else.
  • No screen-reader testing record, and no stated i18n requirement beyond keeping en-US and zh-CN in sync.