From bb9d6e1ebbeff51ccb3f3a62cdd99bb160fa57af Mon Sep 17 00:00:00 2001 From: mrsibe Date: Fri, 25 Sep 2026 01:28:36 +0800 Subject: [PATCH] chore(product): capture PRODUCT.md for the impeccable workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `impeccable context` reports NO_PRODUCT_MD / BUILD_INIT_REQUIRED: DESIGN.md records the visual system, but nothing records product truth, so any new-surface or redesign request is blocked until it exists. The maintainer asked for this to be written directly rather than through the init interview, so nothing in it is an interview answer: - Facts are sourced to the artifact that states them (README, #82, #65, #44, DESIGN.md, CONTRIBUTING.md, package.json). - Everything read out of the code rather than stated is marked `[inferred]`, with a provenance note at the top of the file saying so. - Two contradictions are recorded as open questions instead of being resolved by guessing: the README calls quiz/transcription/slide generation unreleased while quiz and Anki surfaces are implemented, and no accessibility standard is named anywhere. - No image generation is available in this tool surface, so init records no `buildPath` preference. That is a working state, not a gap. The positioning section records what #82 establishes: a citation resolves to a source location and must survive re-chunking, which is why source blocks are persisted and chunks reference them. It also carries the maintainer's own correction — the README's traceability claim ran ahead of the code — as a standing commitment rather than a footnote. --- PRODUCT.md | 191 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 PRODUCT.md diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..639ce98 --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,191 @@ +# 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](#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](#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: + +```text +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). + +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](#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. +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.