# Core ideas: how Undra actually works By the end of this page you will have one mental model of Undra, the one the reference pages quietly assume. Not how to click anything: why the pieces fit together the way they do. Get these six ideas and the rest of the docs stop feeling like a list of features and start feeling like one coherent thing. Each idea is a couple of sentences and a link to where it actually shows up. ## 1. Items are files you own An Undra workspace is an ordinary folder on your disk, and the things inside it are real files, not rows hidden in some database. A note is a Markdown `.md` file you could open in any other editor; plans, canvases, and the rest are Undra's own file formats, but they are still just files sitting in that folder. The payoff is plain: you can back it up, sync it, move it to a new machine, or open it in another tool, because nothing is trapped. See [Local-first trust](/docs/workspace/local-first-trust/) for why this is the foundation, and [Notes](/docs/workspace/notes/) for what one of those files actually looks like on disk. ## 2. Identity lives in the id, not the filename Every item carries a small stable `id` in its frontmatter, and that id, not the filename, is who the item *is*. So you can rename a note or move it to another folder and nothing breaks: the links pointing at it still resolve, its place in any ordering holds, its backlinks stay attached. Filenames stay human and readable precisely because they are not load-bearing; the id does the quiet work underneath. The frontmatter `id` is shown in [Notes](/docs/workspace/notes/) (the real example near the end), and rename-safe linking is the whole point of [Wikilinks & backlinks](/docs/workspace/wikilinks-and-backlinks/). ## 3. The indexes are caches, not your data Search, the graph, and the semantic index are all derived from your files. They are caches the app builds for speed and for finding things; if one were ever lost, Undra just rebuilds it from the files, and none of your actual work is at stake. One exception to know about: the semantic index (search by meaning rather than exact words) is not automatic. It is an explicit, one-time **Build index** step you turn on when you want it. Why indexes are safe to lose is covered in [Local-first trust](/docs/workspace/local-first-trust/); the build-it-once semantic index lives in [Setting up AI](/docs/getting-started/setting-up-ai/), and everyday search is in [Search](/docs/undraverse/search/). ## 4. AI proposes, you review, then it applies AI does not quietly rewrite your files. It proposes a change, you see exactly what it wants to do, and only then does it land, and everything it does is reversible. The autonomy is risk-scaled: safe, recoverable edits can apply on their own, while deletions always stop and ask you first. That mix is what makes it comfortable to hand work to AI without watching every keystroke. The full propose, review, apply flow (including the auto-apply setting and the undo behavior) is documented in [Folder Portals](/docs/workspace/folder-portals/), and the helpers that run it are in [Agents](/docs/workspace/agents/). :::tip You stay the one deciding The rule under all of this: if something changes your workspace, you should be able to see what it changed and why, before it sticks. Risk-scaled autonomy just decides how much it asks first, never whether you can undo. ::: ## 5. Views are lenses, not copies The Calendar, dashboards, the graph, and query widgets do not hold their own data. They are live lenses pointing at the same items. The Calendar is your plan tasks that have dates, laid on a grid; drag one and the underlying plan changes, because there is only one copy. A dashboard that says "due this week" is reading the same tasks, not a separate list you have to keep in sync. This is why edits show up everywhere at once: there is nothing to keep in sync. See the [Calendar](/docs/workspace/calendar/) (a view of dated plan tasks) and [Dashboards](/docs/workspace/dashboards/) (assembled live from your items) for the two clearest examples; the graph view is in [Undraverse](/docs/undraverse/groups-and-presets/). ## 6. Capture first, structure later You do not design a taxonomy before you start. You write things down, and the structure assembles itself out of what you wrote. The mechanism that makes this work is the wikilink: type `[[Some item]]` mid-thought and you get a backlink on the other item and an edge in the graph for free, with no filing. Link as you go, and the map of your work emerges instead of being planned. This is the heart of [Wikilinks & backlinks](/docs/workspace/wikilinks-and-backlinks/); the low-friction surface you usually capture into is [Notes](/docs/workspace/notes/), and the map those links draw is [Undraverse](/docs/undraverse/groups-and-presets/). ## Where to go next - **[The first 15 minutes](/docs/learn/first-15-minutes/)**: put these ideas to work in a short guided run. - **[Adopt your notes](/docs/learn/adopt-your-notes/)**: bring an existing pile of Markdown in without a migration. - **[Local-first trust](/docs/workspace/local-first-trust/)**: the one principle the rest of this builds on.