--- name: how-jot-works-checks description: 21 rules from the Noesa course "How Jot Works — anatomy of a modern web app". For curious non-developers and new developers, taught through a real app as the case study. --- # How Jot Works — anatomy of a modern web app — the rules Use with: Claude Code or Claude (save as a skill), Cursor (save under .cursor/rules as .mdc), ChatGPT or any other assistant (paste the text below into custom instructions or a project's instructions). 21 rules, taken from the course at https://noesa.leafsoft.online/c/how-jot-works Each heading is one thing the course teaches. Most are checks to run on your own output before presenting it as done; a few are background you are expected to have. 12 also name a mistake models make by default, under "Watch for". "Wrong by default" lists 2 specific ones. Apply these to the thing you are producing — the type, the schema, the query, the copy — not only to how you explain it. Where a rule names a field, a format or an identifier, that name belongs in the output. ## Meet Jot, your lab bench Know what Jot is and how this course works — and have Jot open with your first note written. ## Start here: how Jot works Explain what a website really is — browser, server, page — and run this course's daily reading loop. ## Finding a site: addresses, DNS & the padlock Take a URL apart, explain what DNS does, and say what the padlock actually buys you. **Watch for:** If you asked an AI whether a site with a padlock is safe, what could it overstate? It may collapse transport security into total trust because the padlock is the familiar shorthand. HTTPS protects the connection and verifies the domain; it does not prove the site's code, claims, or owner are benign. You still check what the site does after the sealed connection ends. ## The three languages & the two halves Name the jobs of HTML, CSS and JavaScript, split an app into frontend and backend, and read an API call. **Watch for:** If you asked an AI to generate the note-creation API route, what might the shortest working version leave out? It may stop once the request creates a row, because it does not know Jot's trust boundary from the feature request alone. You must check input validation, authentication, and ownership before data reaches the database; a route that works without those checks is not a finished route. ## What Jot is built with Explain what Node.js, TypeScript and React each add on top of the three languages. ## Where your notes live Explain what a database does, the Cloud vs Local trade, and how end-to-end encryption seals the private mode. **Watch for:** If you asked an AI to add a "private mode," what crucial design choice could it invent instead of learning from your system? It may default to the common pattern of storing data on a server behind access controls, because "private" does not specify where plaintext may exist. You must state and verify the boundary: Local notes are encrypted before storage, the key stays in memory, and recovery limits are a consequence of that architecture. ## AI on your terms: your key + embeddings Explain why Jot makes you bring your own AI key, and what an embedding actually is. ## AI that reads your notes: search + Ask AI Contrast vector search with keyword search, and walk the five steps of RAG end to end. **Watch for:** If you asked an AI to build "chat with my notes," what could a fluent demo hide? It may produce an answer before proving which notes were retrieved, because the common demo optimizes for conversation rather than evidence. You must check the corpus boundary, retrieval step, and citations; without those, a polished answer can be unrelated to your notes. ## AI in your own voice: Refine, prompts & skills Explain what Refine does and refuses to do, read a prompt like a spec, and say what a Skill is. **Watch for:** If you asked an AI to "clean up this note," what could it change even when the prose sounds better? It may add plausible detail because a vague request rewards a complete-sounding rewrite. You must compare facts and intent, and give the operation a hard boundary such as "do not add facts." Fluency is not evidence that the note still says what you meant. ## Shipping it: Git, deploy, PWA & the Play Store Trace code from a git commit to a phone: deploy, PWA powers, push notifications, the Play-Store shell, and the passkey lock. **Watch for:** If you asked an AI whether Jot should be rewritten as a native app, what context might its recommendation miss? It may default to the prestige or common capabilities of native development without pricing the second codebase, web feature coverage, deployment model, and actual missing device capability. You must supply those product constraints and choose the smallest wrapper that clears the real bar. ## The whole map + build your own Trace Jot from a browser action through storage and AI retrieval, then publish a small page at a real URL. ## Under the hood: the editor & how a note is stored Explain how Jot stores a note as markdown inside a content envelope and how links and tags survive the editor round trip. **Watch for:** You ask an AI to pull `[[wikilinks]]` out of saved markdown. What detail of this codebase makes its sensible-looking scanner miss them? It may write a correct matcher for clean double brackets while missing that this editor's serializer escapes them first. You must trace the real stored form through the content envelope and test it; generated code cannot infer a transformation you did not show it. ## Under the hood: signing in without passwords Trace Jot's passwordless sign-in flow and explain how a signed session cookie keeps later requests authenticated. **Watch for:** If you asked an AI to add sign-in, what tempting shortcut should make you stop and inspect the design? It may reach for a hand-rolled password flow or a provider-specific convenience because both look shorter in one code sample. You must keep credentials with the identity specialist, use the standard OIDC boundary, and verify session handling; authentication is a system contract, not a form plus a cookie. ## Under the hood: proving it works (tests) Write a behavior-focused test, explain why a bug fix starts with failure, and use parity tests to compare Cloud and Local modes. **Watch for:** If you asked an AI to write tests for a feature, why might a green suite still tell you too little? It may mirror the current implementation or cover the common happy path, because it does not know which behavior is the promise or which past bug matters. You must name the invariant, include the failure case, and reproduce a bug before fixing it; test volume is not the same as protection. ## Under the hood: one app, two engines Explain how Jot's DataAPI contract separates the UI from Cloud and Local storage and name the checks that prevent parity drift. **Watch for:** If you asked an AI to add a data feature to Jot, what could it miss even when the cloud implementation works? It may follow the first visible implementation and stop there because repository context does not automatically become a behavioral requirement. You must check the shared contract, both engines, and the parity scenario; "works in Cloud" is only half a feature in this system. ## Using Jot well: the daily loop Use Jot's capture, refine, review, and connect loop to turn one daily note into trusted, reusable material. ## Using Jot well: tags vs topics Choose tags for reusable kinds of notes and topics for specific subjects, then combine them without creating clutter. **Watch for:** If you asked an AI to build a private topic index, what could a reasonable-looking hash still leak? It may choose an ordinary hash because that is the common indexing pattern, while missing that predictable topic names can be guessed and compared. You must check the threat boundary and use the keyed construction required by Local mode; hiding plaintext is not enough if fingerprints can be enumerated. ## Using Jot well: one subject per section Split a daily note into one-subject sections and explain how that grain improves tags, links, summaries, and retrieval. ## Using Jot well: getting real answers from Ask AI Ask a grounded question, inspect its citations, and improve a weak Ask AI result by fixing the reviewed source material. **Watch for:** If Ask AI gives a confident answer with citations, what can still be wrong? It can retrieve relevant passages and then combine them into a claim no single source supports, because fluent synthesis rewards a coherent story. You must open the citations and verify the exact claim against them; grounding narrows the source material, but judgment closes the loop. **Wrong by default:** - Neither note says this. It is assembled — August, plus two weeks, therefore September — and the word doing the damage is 'therefore'. This is the failure the day warns about: retrieval was perfect, both citations are real, and the model combined them into a claim no single passage supports. A synthesised date is the most dangerous kind, because it is the one that ends up in a plan. - True as far as your notes go — and it directly contradicts the September claim three lines above it. An answer can hold both because it is generating sentences, not maintaining a position. Two claims that cannot both be true is the cheapest tell there is, and it costs nothing to look for. ## Using Jot well: the Daily Brief as a workflow Use the Daily Brief's four lenses and Compile flow to turn unresolved notes into a deliberate daily workflow. ## Using Jot well: make it yours Configure Jot's theme, AI provider, writing voice, notebook personas, and capture tools while keeping your notes portable.