├── LICENSE ├── README.md └── MANIFESTO.md /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Plaintext Commons 2 | 3 | Knowledge should outlast software. 4 | 5 | --- 6 | 7 | ## What is this? 8 | 9 | A design stance for knowledge work where plain text files are the source of truth, not apps. Your folder of Markdown or .txt files *is* the platform. Tools come and go, but your files remain. 10 | 11 | **Read the full manifesto: [plaintextcommons.org](https://plaintextcommons.org)** 12 | 13 | ## The Three Laws 14 | 15 | 1. **The folder is the platform.** 16 | One corpus — a folder of open files — acts as the system of record. 17 | 18 | 2. **The file is the protocol.** 19 | Stable, human-readable plain text (Markdown or .txt) with optional front matter. 20 | 21 | 3. **No tool owns the corpus.** 22 | Tools are non-exclusive and interchangeable. None enforce format or schema. 23 | 24 | ## The Plaintext Test 25 | 26 | Before adopting any tool or workflow: 27 | 28 | 1. Can I read/edit the files with a basic text editor? 29 | 2. Can I move the folder and keep working — no exports required? 30 | 3. Can the tool propose human-auditable changes before writing? 31 | 4. Will this still make sense in ten years? 32 | 33 | If not, it's not Commons-compatible. 34 | 35 | ## This Repository 36 | 37 | Contains the Plaintext Commons manifesto and its evolution. This is a living document based on active research in file-native thinking systems. 38 | 39 | 40 | ## License 41 | 42 | The Unlicense - Public Domain 43 | -------------------------------------------------------------------------------- /MANIFESTO.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Plaintext Commons — Manifesto" 3 | description: "A design stance for an open corpus: the folder is the platform, the file is the protocol, and writes are previewed and reversible. Tools—including AI models from frontier to local—assist without owning the data." 4 | version: "0.2" 5 | date: 2025-11-28 6 | --- 7 | 8 | **Premise:** Knowledge should outlast software. 9 | 10 | **Problem:** Most modern software is cloud-first and app-centric. Each product keeps your data in its own format and database, only reluctantly offering exports and brittle imports. 11 | 12 | **Claim:** A single folder of plain text files you control can act as the shared, durable substrate for people, tools, and agents—a neutral commons where no app owns the data and any tool may participate. 13 | 14 | **Consequence:** Store what matters in _plain text (Markdown or .txt)_ inside a corpus you own. Let tools come and go; the folder remains the source of truth and the bridge between them. 15 | 16 | 17 | ## Why now 18 | 19 | For decades, software has demanded rigid, app-specific formats and server-side databases. Each tool became its own silo; connecting them meant exports, imports, and permanent friction. 20 | 21 | At the same time, two things changed: 22 | - **Local-first & open formats are resurfacing:** users want data that lives on their machines, in formats they can keep using even if vendors disappear. [^1] 23 | - **Modern models read and write text directly** — and most other media can be transcribed into text. The supposed gap between “human-readable” and “machine-readable” is now mostly artificial. [^2] 24 | 25 | Together, this makes a different architecture viable: 26 | - **Data is stable** — plain text files in a folder you control. 27 | - **Tools are interchangeable** — editors, CLIs, and agents operate on those files, not hidden schemas. 28 | - **Intelligence is layered** — search, indexes, and agents understand the corpus without owning it. 29 | 30 | 31 | ## Core principles (non-negotiables) 32 | 33 | 1. **Files over apps.** Your **corpus** (a folder of open files) is the system of record. 34 | 2. **Plain text by default.** Use Markdown or .txt; keep light metadata in _frontmatter_ (or a tiny sidecar file for .txt when necessary). 35 | 3. **Tools assist, they don’t annex.** No tool owns the data or invents a private schema that captures it. 36 | 4. **Writes are previewed and reversible.** Tools propose changes; you review and apply; changes have a clear _provenance trail_. 37 | 5. **Composability beats monoliths.** Many small tools on one shared corpus. 38 | 6. **Minimum ceremony.** Conventions only where they pay for themselves (naming, links, frontmatter). 39 | 7. **Portability and durability.** Ten years from now, the files still open and make sense. 40 | 8. **Privacy first.** Local by default; use cloud only with explicit consent. 41 | 9. **No exports. No migrations.** The folder *is* the platform. 42 | 43 | 44 | 45 | ## The three laws of the Commons 46 | 47 | 1. **The folder is the platform.** 48 | One _corpus_—a folder of open files—acts as the system of record. 49 | 50 | 2. **The file is the protocol.** 51 | Stable, human-readable _plain text (Markdown or .txt)_ with optional _frontmatter_. No opaque blobs. 52 | 53 | 3. **Writes are previewed and reviewable.** 54 | Tools propose changes; you preview and accept; a simple log/history preserves *why* changes happened, not just *what* changed. 55 | 56 | 57 | 58 | ## Multi-tool by design 59 | 60 | Different tools specialize and still cooperate because they share the same substrate: 61 | 62 | - **Authoring** in any editor. 63 | - **Browsing & searching** (exploration and retrieval) via tools—indexers, embeddings, and link graphs. 64 | - **Scripting and automation** with scripts, CLIs or any automation tool. 65 | - **Organizing chores** (linking, filing, light refactors) delegated to tools or agents—without taking ownership of the data. 66 | - **Capture & ingestion** from email, PDFs, and transcripts—converted to text with attachments nearby. 67 | 68 | _No exports. No migrations._ 69 | 70 | 71 | 72 | ## Minimal working conventions 73 | 74 | Keep it robust without bureaucracy: 75 | 76 | - **Shallow corpus.** Let search, links, tags, and tools handle the heavy lifting—including organizing chores. 77 | - **Note schema is optional.** Zettelkasten, Fleeting/Project/Evergreen, or none—your choice. 78 | - **Stable filenames.** Use a simple stamp pattern (e.g., `date + slug`) if it helps. 79 | - **Metadata:** 80 | - _Markdown:_ use frontmatter for light metadata. 81 | - _.txt_: use a tiny sidecar only when needed. 82 | - **Sync/history:** Git, cloud sync, or both—your call. 83 | 84 | 85 | ## Norms for tools (agents included) 86 | 87 | - **Read-only by default; explicit writes.** 88 | - **Previewable changes with rationale.** Generate human-auditable previews before any write. 89 | - **Respect corpus rules.** Honor ignore lists, attachment folders, and local settings. 90 | - **Pipe-friendly I/O.** Text/JSON in and out; compose with other CLIs and tools. 91 | - **AI and agent-aware.** Expose capabilities in open, automatable ways (e.g., MCP/stdio/HTTP)—no proprietary lock-ins. 92 | - **No schema capture.** Indexes are caches; they are purgable and never become the source of truth. 93 | 94 | 95 | 96 | ## Adoption path (practical, not sacred) 97 | 98 | 1. **Start a corpus.** Pick a folder. Make it your system of record. 99 | 2. **Choose light conventions.** Naming, links, and minimal front matter; stop when marginal value drops. 100 | 3. **Add an indexer.** Turn on FTS + embeddings + backlinks; let the index come to the files, not the other way around. 101 | 4. **Introduce a tool/agent.** Examples: [Claude Code](https://docs.anthropic.com/claude/docs/claude-code) (CLI), [Claude.ai](https://claude.ai/) or [ChatGPT](https://chatgpt.com/) (app), or [LM Studio](https://lmstudio.ai/) (local). Use open interfaces (CLI, MCP/stdio/HTTP). 102 | 5. **Require previewable writes.** Propose → preview → apply → log. 103 | 6. **Iterate only where it pays.** Improve naming, linking, tagging, and automation gradually. 104 | 105 | 106 | 107 | ## The Plaintext Test 108 | 109 | Ask this before adopting a tool or workflow: 110 | 111 | 1. Can I read/edit the files with a basic text editor? 112 | 2. Can I move the folder and keep working—no exports required? 113 | 3. Can the tool propose a human-auditable preview of changes (with rationale) before writing? 114 | 4. Will this still make sense in ten years? 115 | 116 | If not, it’s not Commons-compatible. 117 | 118 | 119 | ## Industry note 120 | 121 | This is a **design stance**, not a membership. Build tools that keep data open, changes explainable, and the folder first. Everything else is replaceable. 122 | 123 | 124 | _The initial version of the manifesto is written by [Toto Tvalavadze](https://ttvl.co)._ 125 | 126 | [^1]: Martin Kleppmann, Adam Wiggins, Peter van Hardenberg, and Mark McGranaghan. Local-first software: you own your data, in spite of the cloud. 2019 ACM SIGPLAN International Symposium on New Ideas, New Paradigms, and Reflections on Programming and Software (Onward!), October 2019, pages 154–178. [doi:10.1145/3359591.3359737](https://doi.org/10.1145/3359591.3359737) 127 | [^2]: Large language model (n.d.). In Wikipedia. Retrieved November 28, 2025, from [https://en.wikipedia.org/wiki/Large_language_model](https://en.wikipedia.org/wiki/Large_language_model) 128 | --------------------------------------------------------------------------------