micelio 0.1.0__tar.gz

micelio-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+
+# Tools
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Local config and data
+.env
+micelio.toml
+data/
+*.sqlite3
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

micelio-0.1.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-10
+
+The first release: a folder of Markdown notes shown as a forest of ideas, read-only and
+self-hosted. The project was called Mycelium while it was built; it is released as Micelio
+(Spanish for mycelium).
+
+### Added
+
+**Reading the vault**
+
+- Vault reader: frontmatter, titles and Obsidian-style wikilinks (aliases, headings, paths);
+  hidden folders and Syncthing conflict copies are skipped.
+- In-memory index with backlinks, project membership, bridges, ghost links and orphans,
+  refreshed from file modification times.
+- `micelio check` lists problems in a vault; `micelio serve` runs the site.
+- `micelio.toml` loading and validation: site, vault folders, categories with mushroom
+  species, graph, landing, typography, sign-in and data folder.
+
+**Pages**
+
+- The landing: the vault drawn as a forest over a painted background. Projects are
+  mushrooms (eight species, grown by status, sized by notes), notes are spore clouds in
+  the mycelium, links are hyphae with sparks, sources are crystals and the latest journal
+  notes are golden spores; positions from a vendored, seeded d3-force.
+- The graph of everything at `/explore`, with search and filters, plus a graph on every
+  project and note page, all drawn as mycelium by the same engine (`static/js/draw.js`);
+  `graph.max_nodes` keeps big vaults readable.
+- Reading pages: projects by category, each project with its notes and conversations,
+  notes with backlinks and the projects they belong to, the journal and a health page.
+- Markdown rendered like Obsidian (wikilinks, ghost links, callouts, task lists, tables,
+  footnotes) and sanitized with nh3.
+- `/api/graph` and `/api/landing` with the same data as the pages; `/healthz` for
+  containers and monitoring.
+
+**Look**
+
+- One dark look on every page: the painted background, text on ink glass, pill buttons.
+- The Appearance page (`/appearance`): four palettes (Psychedelic, Tokyo Night, Catppuccin
+  Mocha, Rosé Pine) that recolor the background, the mushrooms and the categories; an
+  uploaded background; the soil line; the title, tagline and site name; fonts, title
+  effect and sizes; and a prompt builder for painting a background with any image
+  generator. Saved in the data folder, never in the vault. Seven fonts ship with
+  Micelio (SIL OFL).
+
+**Languages**
+
+- English and Spanish interfaces, including the names of the default categories; own
+  categories take `label = "Art"` or `label = { en = "Art", es = "Arte" }`; dates per
+  language and in the configured time zone. Adding a language takes one file.
+
+**Sign-in and sharing**
+
+- Sign-in for one person: argon2 password and TOTP code, server-side sessions in SQLite,
+  lockout after repeated failures, `auth.mode = "none"` for gateways, and `micelio user`
+  commands to create the secrets. On `127.0.0.1` with no secrets, sign-in is off.
+- Public notes: anonymous visitors see the landing, `/explore`, `/projects`, the journal
+  and the APIs built from `public: true` notes only. Private notes do not exist for them:
+  no titles, links, nodes, ghosts or counts, and their URLs answer 404.
+- Security headers (CSP without inline code, no framing) on every response.
+
+**Installing**
+
+- A Docker image, `ghcr.io/0xpietri/micelio`, for `linux/amd64` and `linux/arm64`: a
+  non-root user, a read-only root filesystem, the vault mounted read-only, one data volume
+  and a health check. `compose.example.yml` runs it on the sample vault in one command.
+- The Python package `micelio` on PyPI: `uvx micelio serve --vault ~/Notes`.
+- `micelio serve` takes its defaults from `MICELIO_HOST`, `MICELIO_PORT` and
+  `MICELIO_FORWARDED_ALLOW_IPS`.
+- Self-hosting guides for Micelio plus a notes MCP server, on your own computer or on a
+  server.
+- A sample vault in `examples/vault`, CI on Linux, macOS and Windows, and releases from a
+  tag (image, package and GitHub release).
+
+[Unreleased]: https://github.com/0xpietri/micelio/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/0xpietri/micelio/releases/tag/v0.1.0

micelio-0.1.0/Dockerfile

@@ -0,0 +1,54 @@
+# syntax=docker/dockerfile:1
+# Micelio: one small container that reads a vault mounted read-only.
+
+ARG PYTHON_VERSION=3.12
+
+# --- build: resolve the locked dependencies and install the package into /app/.venv
+FROM ghcr.io/astral-sh/uv:0.13 AS uv
+FROM python:${PYTHON_VERSION}-slim AS build
+COPY --from=uv /uv /usr/local/bin/uv
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    UV_PROJECT_ENVIRONMENT=/app/.venv
+WORKDIR /src
+# Dependencies first, so editing the code does not reinstall them.
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev --no-install-project
+COPY README.md LICENSE ./
+COPY src ./src
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev --no-editable
+
+# --- runtime: Python and the virtual environment, nothing else
+FROM python:${PYTHON_VERSION}-slim
+ARG VERSION=dev
+LABEL org.opencontainers.image.title="Micelio" \
+      org.opencontainers.image.description="Your Markdown notes as a living network of ideas" \
+      org.opencontainers.image.source="https://github.com/0xpietri/micelio" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.version="${VERSION}"
+
+RUN groupadd --gid 10001 micelio \
+ && useradd --uid 10001 --no-log-init --gid micelio --no-create-home --home-dir /data micelio \
+ && mkdir -p /vault /data \
+ && chown micelio:micelio /data
+COPY --from=build /app/.venv /app/.venv
+
+ENV PATH=/app/.venv/bin:$PATH \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    MICELIO_VAULT=/vault \
+    MICELIO_DATA=/data \
+    MICELIO_HOST=0.0.0.0 \
+    MICELIO_PORT=8765
+
+USER micelio
+WORKDIR /data
+VOLUME ["/data"]
+EXPOSE 8765
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen(f\"http://127.0.0.1:{os.environ.get('MICELIO_PORT', '8765')}/healthz\", timeout=4)"]
+ENTRYPOINT ["micelio"]
+CMD ["serve"]

micelio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Pietri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

micelio-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: micelio
+Version: 0.1.0
+Summary: Your Markdown notes as a living network of ideas: projects, graphs and links, self-hosted and read-only.
+Project-URL: Homepage, https://github.com/0xpietri/micelio
+Project-URL: Issues, https://github.com/0xpietri/micelio/issues
+Project-URL: Changelog, https://github.com/0xpietri/micelio/blob/main/CHANGELOG.md
+Author: Marcos Pietri
+License-Expression: MIT
+License-File: LICENSE
+Keywords: knowledge-graph,markdown,mcp,obsidian,second-brain,zettelkasten
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: babel>=2.16
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: nh3>=0.2.18
+Requires-Dist: pydantic>=2.9
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qrcode>=8.0
+Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
+Requires-Dist: uvicorn>=0.32
+Description-Content-Type: text/markdown
+
+# Micelio
+
+**Your Markdown notes as a living network of ideas.** Micelio reads a folder of notes (an
+Obsidian vault, or any folder of `.md` files) and shows it as projects, links and graphs on a
+small self-hosted website. It is read-only: your notes stay plain files that you, your editor
+or an AI assistant write.
+
+*Micelio* is Spanish for mycelium, the web of threads that grows under a forest; say
+"mee-SEH-lyo".
+
+[![CI](https://github.com/0xpietri/micelio/actions/workflows/ci.yml/badge.svg)](https://github.com/0xpietri/micelio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/micelio)](https://pypi.org/project/micelio/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+![The sample vault in Micelio: projects grow as mushrooms over a forest of notes, then the
+whole graph drawn as micelio](docs/images/micelio.gif)
+
+## Why
+
+Notes written over months, by hand or by an assistant over [MCP](https://modelcontextprotocol.io),
+pile up into a web of ideas that a file list cannot show. Micelio makes that web visible:
+
+- **Projects** grow above ground like mushrooms; the **notes** they link to spread below as
+  mycelium, and notes shared by projects of different categories become visible **bridges**.
+- **Graphs** for the whole vault, for each project and around each note.
+- **Health**: broken links (shown as ghost nodes), unknown frontmatter values and orphans.
+- **Sharing**: mark a note `public: true` and anonymous visitors can read it; everything else
+  needs a sign-in.
+- **Any assistant**: Micelio does not care who wrote the notes. Claude, ChatGPT, a local
+  model or you in Obsidian all work.
+
+## Quick start
+
+**Try it** on the bundled sample vault, with Docker:
+
+```sh
+git clone https://github.com/0xpietri/micelio
+cd micelio
+docker compose -f compose.example.yml up        # http://localhost:8765
+```
+
+**On your own computer**, with [uv](https://docs.astral.sh/uv/) (Linux, macOS or Windows),
+no Docker needed:
+
+```sh
+uvx micelio serve --vault ~/Obsidian     # http://127.0.0.1:8765
+```
+
+(or `pipx install micelio`, then `micelio serve --vault ~/Obsidian`). On
+`127.0.0.1` sign-in is off until you set it up; nobody else can reach it.
+
+**On a server**, run the image `ghcr.io/0xpietri/micelio` (amd64 and arm64, so a Raspberry
+Pi works too) with the vault mounted read-only:
+
+```sh
+docker run -d --name micelio --read-only --tmpfs /tmp -p 127.0.0.1:8765:8765 \
+  -v ~/Obsidian:/vault:ro -v micelio-data:/data --env-file .env \
+  ghcr.io/0xpietri/micelio:0.1
+```
+
+`.env` holds the sign-in secrets (see [Signing in](#signing-in)); put a reverse proxy with
+TLS (Caddy, Nginx, Traefik) in front. [`compose.example.yml`](compose.example.yml) shows the
+same as a Compose file, and the [server guide](docs/guides/self-hosting-server.md) walks
+through a whole setup with a notes MCP server.
+
+To work on Micelio itself, see [CONTRIBUTING.md](CONTRIBUTING.md): `uv sync`, then
+`uv run micelio serve --vault examples/vault`.
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph writers [Who writes]
+        A["AI assistant<br/>(Claude, ChatGPT, local model)"] -->|MCP| M[Notes MCP server]
+        O[You in Obsidian]
+    end
+    M --> V[("Vault<br/>Markdown files")]
+    O --> V
+    V -->|read-only| R
+    subgraph app [Micelio: one process]
+        R[Vault reader<br/>frontmatter + wikilinks] --> I[In-memory index<br/>links, projects, bridges]
+        I --> P[Pages<br/>FastAPI + Jinja]
+        I --> J["/api/graph, /api/landing"]
+        S[("data/<br/>SQLite: sessions,<br/>Appearance")] --- P
+    end
+    P --> B[Browser]
+    J --> B
+    B -.->|"draw.js + d3-force<br/>mushrooms and hyphae"| B
+```
+
+- The vault is the only source of truth. Micelio re-reads files when they change and keeps
+  the index in memory; delete its data folder and nothing is lost.
+- Its own state (sign-in sessions, the Appearance page's choices, an uploaded background)
+  lives in a small SQLite file in the data folder, never in the vault.
+- Pages are rendered on the server; the landing and the graphs are plain JavaScript modules
+  over JSON, with vendored libraries and no build step.
+- Anonymous visitors get a filtered view built from `public: true` notes only.
+
+## Talking to your notes
+
+Micelio shows notes; an MCP server writes them when you talk to an assistant, from a desktop
+app or from your phone in voice mode. The [self-hosting guides](docs/guides/README.md) set up
+both, either [on your own computer](docs/guides/self-hosting-computer.md) (Linux, macOS,
+Windows) or [on a server](docs/guides/self-hosting-server.md).
+
+## How a vault is read
+
+```
+vault/
+  projects/   one note per project, with a category; it links to its notes
+  notes/      one idea per note
+  journal/    dated entries
+  sources/    books, papers, links
+```
+
+Each note may start with a frontmatter block:
+
+```yaml
+---
+type: project            # project | note | journal | source (otherwise taken from the folder)
+category: science        # projects only; one of the categories in micelio.toml
+status: active           # draft | active | paused | closed
+tags: [gravity, astrology]
+created: 2026-11-09
+public: false            # true lets anonymous visitors read it
+aliases: [Planets at birth]
+---
+```
+
+Links use Obsidian's `[[wikilink]]` syntax, including `[[Note#Heading|label]]`, aliases and
+paths. A note belongs to a project when the project links to it. Hidden folders (`.obsidian`,
+`.trash`) and Syncthing conflict copies are ignored. Nothing in the frontmatter is required;
+odd values are reported by `micelio check`, never fatal.
+
+## Interface languages
+
+The interface ships in English and Spanish (`language = "es"` in `micelio.toml`); your notes
+are always shown as written. Adding a language takes one file, see
+[CONTRIBUTING.md](CONTRIBUTING.md#adding-a-language).
+
+## Configuration
+
+Copy [`micelio.example.toml`](micelio.example.toml) to `micelio.toml` and point
+`--config` (or `MICELIO_CONFIG`) at it. It holds the site title, the owner's name, the vault
+folders and the categories, each with a mushroom species for the landing page.
+Secrets never go in this file; see [`.env.example`](.env.example).
+
+## The landing and its look
+
+The home page draws your vault as a forest: each project is a mushroom above the soil (its
+species comes from the category, its size from its notes, its shape from its status), notes
+are clouds of spores in the mycelium below, links are threads, sources are crystals and the
+latest journal notes float as golden spores. Hover for titles, click to open.
+
+Signed in, **Appearance** (`/appearance`) changes how it looks: four palettes (Psychedelic,
+Tokyo Night, Catppuccin Mocha, Rosé Pine), your own background image, where the soil starts,
+and the title and tagline. It also builds a prompt you can paste into any image generator to
+paint a background that fits. These choices are saved in the data folder, never in your notes;
+`[landing]` in the config sets the defaults.
+
+## Signing in
+
+One person signs in, with a password and a code from an authenticator app (any TOTP app:
+Aegis, 2FAS, Google Authenticator, 1Password…). Generate the three secrets once and put them
+in your environment:
+
+```sh
+micelio user set-password    # prints MICELIO_PASSWORD_HASH
+micelio user totp            # shows a QR code, prints MICELIO_TOTP_SECRET
+micelio user session-key     # prints MICELIO_SESSION_KEY
+```
+
+- Sessions last 12 hours and are stored server-side, so signing out really ends them.
+  `micelio user sign-out-all` ends every session.
+- Five failed attempts from one address lock it out for 15 minutes.
+- On your own computer, `micelio serve` listens on `127.0.0.1` only; with no secrets set,
+  sign-in is simply off there. On any other address, Micelio refuses to start without them.
+- Already behind Cloudflare Access, Authelia or another gateway? Set `auth.mode = "none"` and
+  Micelio trusts whoever reaches it. Only do this when the gateway really guards every path.
+
+## Security
+
+- Micelio never writes to the vault; mount it read-only. The image runs as a non-root user
+  with a read-only root filesystem and writes only to `/data`.
+- Anonymous visitors see notes marked `public: true` and nothing else: no private titles,
+  links, counts or ghost nodes, and a private note's URL answers 404.
+- Sign-in is a password plus a TOTP code, with server-side sessions and a lockout. Micelio
+  refuses to listen on a public address without its secrets, unless you say a gateway
+  handles sign-in (`auth.mode = "none"`).
+- Every response carries a strict Content Security Policy (no inline code, no framing), and
+  note bodies are sanitized.
+- Secrets live in the environment, never in `micelio.toml`. Report problems privately, see
+  [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+- **v0.1** (this release): the landing, the graphs, the reading pages, sign-in, public notes,
+  the Appearance page, English and Spanish, Docker image and PyPI package.
+- **v0.2**: a static export of the public notes, to share them without a server
+  (GitHub Pages, Cloudflare Pages, Netlify or a zip).
+- **v0.3**: an Obsidian plugin with the landing and the graph inside Obsidian.
+
+The full specification is in [`docs/spec`](docs/spec/MICELIO_SPEC_v0.1.md); what changed in
+each version is in the [CHANGELOG](CHANGELOG.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Marcos Pietri

micelio-0.1.0/README.md

@@ -0,0 +1,212 @@
+# Micelio
+
+**Your Markdown notes as a living network of ideas.** Micelio reads a folder of notes (an
+Obsidian vault, or any folder of `.md` files) and shows it as projects, links and graphs on a
+small self-hosted website. It is read-only: your notes stay plain files that you, your editor
+or an AI assistant write.
+
+*Micelio* is Spanish for mycelium, the web of threads that grows under a forest; say
+"mee-SEH-lyo".
+
+[![CI](https://github.com/0xpietri/micelio/actions/workflows/ci.yml/badge.svg)](https://github.com/0xpietri/micelio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/micelio)](https://pypi.org/project/micelio/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+![The sample vault in Micelio: projects grow as mushrooms over a forest of notes, then the
+whole graph drawn as micelio](docs/images/micelio.gif)
+
+## Why
+
+Notes written over months, by hand or by an assistant over [MCP](https://modelcontextprotocol.io),
+pile up into a web of ideas that a file list cannot show. Micelio makes that web visible:
+
+- **Projects** grow above ground like mushrooms; the **notes** they link to spread below as
+  mycelium, and notes shared by projects of different categories become visible **bridges**.
+- **Graphs** for the whole vault, for each project and around each note.
+- **Health**: broken links (shown as ghost nodes), unknown frontmatter values and orphans.
+- **Sharing**: mark a note `public: true` and anonymous visitors can read it; everything else
+  needs a sign-in.
+- **Any assistant**: Micelio does not care who wrote the notes. Claude, ChatGPT, a local
+  model or you in Obsidian all work.
+
+## Quick start
+
+**Try it** on the bundled sample vault, with Docker:
+
+```sh
+git clone https://github.com/0xpietri/micelio
+cd micelio
+docker compose -f compose.example.yml up        # http://localhost:8765
+```
+
+**On your own computer**, with [uv](https://docs.astral.sh/uv/) (Linux, macOS or Windows),
+no Docker needed:
+
+```sh
+uvx micelio serve --vault ~/Obsidian     # http://127.0.0.1:8765
+```
+
+(or `pipx install micelio`, then `micelio serve --vault ~/Obsidian`). On
+`127.0.0.1` sign-in is off until you set it up; nobody else can reach it.
+
+**On a server**, run the image `ghcr.io/0xpietri/micelio` (amd64 and arm64, so a Raspberry
+Pi works too) with the vault mounted read-only:
+
+```sh
+docker run -d --name micelio --read-only --tmpfs /tmp -p 127.0.0.1:8765:8765 \
+  -v ~/Obsidian:/vault:ro -v micelio-data:/data --env-file .env \
+  ghcr.io/0xpietri/micelio:0.1
+```
+
+`.env` holds the sign-in secrets (see [Signing in](#signing-in)); put a reverse proxy with
+TLS (Caddy, Nginx, Traefik) in front. [`compose.example.yml`](compose.example.yml) shows the
+same as a Compose file, and the [server guide](docs/guides/self-hosting-server.md) walks
+through a whole setup with a notes MCP server.
+
+To work on Micelio itself, see [CONTRIBUTING.md](CONTRIBUTING.md): `uv sync`, then
+`uv run micelio serve --vault examples/vault`.
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph writers [Who writes]
+        A["AI assistant<br/>(Claude, ChatGPT, local model)"] -->|MCP| M[Notes MCP server]
+        O[You in Obsidian]
+    end
+    M --> V[("Vault<br/>Markdown files")]
+    O --> V
+    V -->|read-only| R
+    subgraph app [Micelio: one process]
+        R[Vault reader<br/>frontmatter + wikilinks] --> I[In-memory index<br/>links, projects, bridges]
+        I --> P[Pages<br/>FastAPI + Jinja]
+        I --> J["/api/graph, /api/landing"]
+        S[("data/<br/>SQLite: sessions,<br/>Appearance")] --- P
+    end
+    P --> B[Browser]
+    J --> B
+    B -.->|"draw.js + d3-force<br/>mushrooms and hyphae"| B
+```
+
+- The vault is the only source of truth. Micelio re-reads files when they change and keeps
+  the index in memory; delete its data folder and nothing is lost.
+- Its own state (sign-in sessions, the Appearance page's choices, an uploaded background)
+  lives in a small SQLite file in the data folder, never in the vault.
+- Pages are rendered on the server; the landing and the graphs are plain JavaScript modules
+  over JSON, with vendored libraries and no build step.
+- Anonymous visitors get a filtered view built from `public: true` notes only.
+
+## Talking to your notes
+
+Micelio shows notes; an MCP server writes them when you talk to an assistant, from a desktop
+app or from your phone in voice mode. The [self-hosting guides](docs/guides/README.md) set up
+both, either [on your own computer](docs/guides/self-hosting-computer.md) (Linux, macOS,
+Windows) or [on a server](docs/guides/self-hosting-server.md).
+
+## How a vault is read
+
+```
+vault/
+  projects/   one note per project, with a category; it links to its notes
+  notes/      one idea per note
+  journal/    dated entries
+  sources/    books, papers, links
+```
+
+Each note may start with a frontmatter block:
+
+```yaml
+---
+type: project            # project | note | journal | source (otherwise taken from the folder)
+category: science        # projects only; one of the categories in micelio.toml
+status: active           # draft | active | paused | closed
+tags: [gravity, astrology]
+created: 2026-11-09
+public: false            # true lets anonymous visitors read it
+aliases: [Planets at birth]
+---
+```
+
+Links use Obsidian's `[[wikilink]]` syntax, including `[[Note#Heading|label]]`, aliases and
+paths. A note belongs to a project when the project links to it. Hidden folders (`.obsidian`,
+`.trash`) and Syncthing conflict copies are ignored. Nothing in the frontmatter is required;
+odd values are reported by `micelio check`, never fatal.
+
+## Interface languages
+
+The interface ships in English and Spanish (`language = "es"` in `micelio.toml`); your notes
+are always shown as written. Adding a language takes one file, see
+[CONTRIBUTING.md](CONTRIBUTING.md#adding-a-language).
+
+## Configuration
+
+Copy [`micelio.example.toml`](micelio.example.toml) to `micelio.toml` and point
+`--config` (or `MICELIO_CONFIG`) at it. It holds the site title, the owner's name, the vault
+folders and the categories, each with a mushroom species for the landing page.
+Secrets never go in this file; see [`.env.example`](.env.example).
+
+## The landing and its look
+
+The home page draws your vault as a forest: each project is a mushroom above the soil (its
+species comes from the category, its size from its notes, its shape from its status), notes
+are clouds of spores in the mycelium below, links are threads, sources are crystals and the
+latest journal notes float as golden spores. Hover for titles, click to open.
+
+Signed in, **Appearance** (`/appearance`) changes how it looks: four palettes (Psychedelic,
+Tokyo Night, Catppuccin Mocha, Rosé Pine), your own background image, where the soil starts,
+and the title and tagline. It also builds a prompt you can paste into any image generator to
+paint a background that fits. These choices are saved in the data folder, never in your notes;
+`[landing]` in the config sets the defaults.
+
+## Signing in
+
+One person signs in, with a password and a code from an authenticator app (any TOTP app:
+Aegis, 2FAS, Google Authenticator, 1Password…). Generate the three secrets once and put them
+in your environment:
+
+```sh
+micelio user set-password    # prints MICELIO_PASSWORD_HASH
+micelio user totp            # shows a QR code, prints MICELIO_TOTP_SECRET
+micelio user session-key     # prints MICELIO_SESSION_KEY
+```
+
+- Sessions last 12 hours and are stored server-side, so signing out really ends them.
+  `micelio user sign-out-all` ends every session.
+- Five failed attempts from one address lock it out for 15 minutes.
+- On your own computer, `micelio serve` listens on `127.0.0.1` only; with no secrets set,
+  sign-in is simply off there. On any other address, Micelio refuses to start without them.
+- Already behind Cloudflare Access, Authelia or another gateway? Set `auth.mode = "none"` and
+  Micelio trusts whoever reaches it. Only do this when the gateway really guards every path.
+
+## Security
+
+- Micelio never writes to the vault; mount it read-only. The image runs as a non-root user
+  with a read-only root filesystem and writes only to `/data`.
+- Anonymous visitors see notes marked `public: true` and nothing else: no private titles,
+  links, counts or ghost nodes, and a private note's URL answers 404.
+- Sign-in is a password plus a TOTP code, with server-side sessions and a lockout. Micelio
+  refuses to listen on a public address without its secrets, unless you say a gateway
+  handles sign-in (`auth.mode = "none"`).
+- Every response carries a strict Content Security Policy (no inline code, no framing), and
+  note bodies are sanitized.
+- Secrets live in the environment, never in `micelio.toml`. Report problems privately, see
+  [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+- **v0.1** (this release): the landing, the graphs, the reading pages, sign-in, public notes,
+  the Appearance page, English and Spanish, Docker image and PyPI package.
+- **v0.2**: a static export of the public notes, to share them without a server
+  (GitHub Pages, Cloudflare Pages, Netlify or a zip).
+- **v0.3**: an Obsidian plugin with the landing and the graph inside Obsidian.
+
+The full specification is in [`docs/spec`](docs/spec/MICELIO_SPEC_v0.1.md); what changed in
+each version is in the [CHANGELOG](CHANGELOG.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Marcos Pietri

micelio-0.1.0/compose.example.yml

@@ -0,0 +1,36 @@
+# Micelio with Docker Compose.
+#
+# Try it on the bundled sample vault, from a clone of the repository:
+#
+#     docker compose -f compose.example.yml up
+#
+# and open http://localhost:8765. The demo turns sign-in off and only listens on this
+# computer. For your own notes, copy this file to compose.yml and follow the comments.
+
+services:
+  micelio:
+    image: ghcr.io/0xpietri/micelio:0.1
+    # build: .                          # or build the image from this folder
+    restart: unless-stopped
+    read_only: true                     # the image writes only to /data (and /tmp)
+    tmpfs:
+      - /tmp
+    cap_drop: [ALL]
+    security_opt:
+      - no-new-privileges:true
+    ports:
+      - "127.0.0.1:8765:8765"           # behind a reverse proxy, keep it on 127.0.0.1
+    volumes:
+      - ./examples/vault:/vault:ro      # your vault: e.g. ~/Obsidian:/vault:ro
+      - ./examples/demo.toml:/config/micelio.toml:ro   # your micelio.toml
+      - micelio-data:/data             # sessions and the Appearance page's choices
+    environment:
+      MICELIO_CONFIG: /config/micelio.toml
+      # Behind a reverse proxy on the host, trust it for the visitor's address
+      # (used by the sign-in lockout). Docker networks usually sit in 172.16.0.0/12:
+      # MICELIO_FORWARDED_ALLOW_IPS: 172.16.0.0/12
+    # With sign-in on, put the three secrets from `micelio user ...` in .env:
+    # env_file: .env
+
+volumes:
+  micelio-data: