logseq-graph-living-atlas 0.1.0

package/.env.example

@@ -0,0 +1,29 @@
+# Copy to .env.local for local source runs:
+# cp .env.example .env.local
+#
+# LOGSEQ_ROOT must point at the graph folder that contains pages/.
+LOGSEQ_ROOT=/absolute/path/to/your/logseq/graph
+
+# Local service port.
+LIVING_ATLAS_PORT=8787
+
+# Snapshot cache path. Leave empty to use the OS user cache directory.
+LIVING_ATLAS_CACHE=
+
+# Real graph reads are token-protected by default.
+# Leave empty to let the CLI generate a one-time local session token.
+LIVING_ATLAS_TOKEN=
+LIVING_ATLAS_REQUIRE_TOKEN=1
+
+# Fixture-only local development escape hatches.
+LIVING_ATLAS_ALLOW_UNAUTHENTICATED_READ=0
+LIVING_ATLAS_ALLOW_UNAUTHENTICATED_REINDEX=0
+
+# Split frontend/API development. Example:
+# LIVING_ATLAS_ALLOWED_ORIGINS=http://127.0.0.1:5177
+LIVING_ATLAS_ALLOWED_ORIGINS=
+
+# Diagnostics and ingest guardrails.
+LIVING_ATLAS_DEBUG_PATHS=0
+LIVING_ATLAS_MAX_FILES=250000
+LIVING_ATLAS_MAX_FILE_BYTES=2097152

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.1.0 - 2026-06-01
+
+Initial public-ready package.
+
+- Local-only Logseq markdown index service.
+- Cinematic Three.js atlas UI with clusters, focus, pathfinding, timeline replay, connector radar, review flags, and local graph delta stream.
+- Public fixture demo for install and UI smoke tests.
+- Runtime API validators, cache envelope validation, and stale-cache rebuilds.
+- Content-aware manifest fingerprints that invalidate cache/watch state even for same-size timestamp-preserving rewrites.
+- 1k, 10k, and 100k synthetic scale evaluation.
+- Configurable service-scale evaluation with normal 10k CI coverage and opt-in 100k disk/watch coverage.
+- WebGL fallback panel for unsupported browsers.
+- Optional token mode for all `/api/*` routes.
+- Real graph CLI runs token-protect `/api/*` reads by default.
+- Programmatic service factory reads are token-required by default unless unauthenticated local reads are explicit.
+- Non-WebGL fallback that still exposes top regions, high-signal pages, and actionable atlas intelligence.
+- Adaptive cinematic/balanced/safe renderer quality tiers for 1k, 10k, and 100k-scale graphs.
+- Budgeted `/api/snapshot` defaults and no-store API responses for safer large/private graph reads.
+- Stable graph-local review storage with an in-app local-data reset.
+- New review flags store graph-scoped hashed node references instead of page names or source paths.
+- Legacy review flags are sanitized during migration so browser storage no longer retains page names or source paths.
+- Compact SSE graph deltas with change counts and sampled live events.
+- Per-snapshot lookup indexes for search, focus, node detail, and pathfinding.
+- Capped node-detail edge samples with full inbound/outbound totals for hub pages.
+- Public source adapter contract and adapter authoring guide.
+- Package-name CLI alias, CSP-protected static HTML, and public issue/support scaffolding.
+- Maintainer, governance, and contribution-process docs for public review and release discipline.
+- Fixture-generated README gallery covering overview, source detail, pathfinding, and connector radar.
+- Keyboard-first mode switching, replay stepping, and search escape behavior.
+
+Known limitations:
+
+- Large graphs render a sampled overview; full 100k-node inspection requires focused slices.
+- Timeline replay is based on current file mtimes, not a historical event log.
+- The fallback renderer supports basic graph exploration, but the cinematic field still requires WebGL.
+- The filesystem Logseq adapter is the only source adapter in this release.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code Of Conduct
+
+Living Atlas follows the Contributor Covenant Code of Conduct, version 2.1.
+
+## Our Pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- using welcoming and inclusive language;
+- respecting different viewpoints and experiences;
+- accepting constructive feedback;
+- focusing on what is best for the community;
+- showing empathy toward other community members.
+
+Examples of unacceptable behavior include:
+
+- sexualized language or imagery;
+- insulting or derogatory comments;
+- public or private harassment;
+- publishing others' private information without explicit permission;
+- conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Enforcement
+
+Report unacceptable behavior through the repository's private security or maintainer contact path when available. Maintainers may remove comments, close issues, or restrict participation for behavior that violates this code.
+
+## Attribution
+
+This code is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contributing
+
+## Development
+
+Use Node 20 or newer.
+
+```bash
+npm install
+npx playwright install chromium
+npm run dev:api -- --root /absolute/path/to/logseq
+npm run dev
+```
+
+For real graph work, the API is token-protected by default. Either open the `#token=...` URL printed by `dev:api`, or set a known local token:
+
+```bash
+LIVING_ATLAS_TOKEN=<random-local-token> npm run dev:api -- --root /absolute/path/to/logseq --allowed-origin http://127.0.0.1:5177
+npm run dev
+```
+
+Open `http://127.0.0.1:5177/#token=<random-local-token>`.
+
+For a production-style local run:
+
+```bash
+npm run build
+npm run serve -- --root /absolute/path/to/logseq
+```
+
+Open the printed `#token=...` URL. Real graph reads are token-protected by default.
+
+## Branches And Pull Requests
+
+Use `main` as the only default branch target. Do not propose or document `master`.
+
+Keep pull requests focused. A good PR changes one behavior, one doc area, or one test gap. Split visual changes, parser changes, service security changes, and packaging changes when they can be reviewed independently.
+
+Branch names should be short and descriptive:
+
+```text
+fix/token-auth-default
+docs/source-adapter-guide
+test/parser-alias-fixture
+```
+
+Every PR should include:
+
+- what changed and why;
+- the validation commands run;
+- whether screenshots or graph payloads came only from the generated fixture;
+- docs updates when API payloads, CLI flags, config, storage, or public terminology changed.
+
+Small first changes that are usually reviewable:
+
+- add one parser fixture for unsupported Logseq syntax;
+- improve one troubleshooting entry;
+- tighten one public term and update the matching test expectation;
+- add a generated fixture screenshot path without real graph data.
+
+## Validation
+
+Before proposing a change, run:
+
+```bash
+npm run validate
+```
+
+On Linux CI-like machines, install the browser and system dependencies with `npx playwright install --with-deps chromium`.
+
+Use targeted commands while iterating:
+
+```bash
+npm test
+npm run check:runtime
+npm run eval
+npm run test:ui
+npm run check:public
+```
+
+`npm run test:ui` uses a generated fixture graph. It does not read your real Logseq graph unless you explicitly set up a separate manual run.
+
+Use `npm run eval:service:100k` only when changing the service scale path or watch behavior. It is intentionally heavier than normal CI.
+
+## Code Style
+
+- Prefer small pure helpers for graph math, filtering, budgets, and rendering policy.
+- Keep filesystem reads in `server/logseq/` or source adapters.
+- Keep HTTP/cache/watch behavior in `server/service.mjs`.
+- Keep React components prop-driven and avoid direct API/storage side effects in leaf components.
+- Update runtime validators before relying on a new API field.
+- Use generated fixtures for tests; do not copy real Logseq graph content into the repo.
+
+## Design Rules
+
+- Keep the graph visually cinematic but operationally truthful.
+- Do not imply provenance that is not present in the indexed Logseq graph.
+- Do not make every decorative particle clickable. Real page nodes are the interaction targets.
+- Do not draw every edge in overview mode.
+- Keep local-only security constraints intact.
+- Keep graph writes out of this app. Writeback belongs in a guarded MCP layer.
+
+## Public-Safety Rules
+
+Target `main` for all public work. Do not create or target any alternate default branch.
+
+Do not commit real graph data, screenshots from a real graph, generated caches, private `.env` files, or machine-specific paths.
+
+Run `npm run check:public` before publishing or opening a public PR.
+
+## Architecture Links
+
+- `docs/ARCHITECTURE.md` explains runtime boundaries, cache, scale, and verification policy.
+- `docs/REPO_GUIDE.md` maps file ownership.
+- `docs/API.md` documents HTTP contracts.
+- `docs/ADAPTERS.md` documents source adapter requirements.
+- `SECURITY.md` and `SUPPORT.md` define private-data handling and report boundaries.

package/GOVERNANCE.md

@@ -0,0 +1,40 @@
+# Governance
+
+Living Atlas uses maintainer-led governance for the first public releases.
+
+## Decision Model
+
+Maintainers make final decisions for roadmap, release, security, and architecture boundaries. Contributors are encouraged to open issues and pull requests, but changes must preserve the project constraints:
+
+- local-first operation;
+- read-only visualization service;
+- no remote listener by default;
+- no committed real graph data;
+- no direct graph writes from the renderer;
+- public documentation and examples based on generated fixture data.
+
+## Scope Changes
+
+Changes that affect trust boundaries require explicit design review before implementation. This includes:
+
+- remote access;
+- authentication changes;
+- MCP or Logseq writeback flows;
+- new source adapters;
+- persistent storage format changes;
+- large-graph cache or database changes;
+- public package/release automation.
+
+## Roadmap
+
+The roadmap is intentionally conservative. Visual quality matters, but graph-derived truth, local security, and public-safe onboarding have priority over cinematic effects that cannot be explained from indexed data.
+
+## Conflict Resolution
+
+When there is disagreement, maintainers should decide using this order:
+
+1. protect user graph privacy and local security;
+2. preserve correctness of graph-derived claims;
+3. keep the app installable and testable from public source;
+4. preserve cinematic quality without obscuring utility;
+5. minimize maintenance burden.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logseq Graph Living Atlas contributors
+
+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.

package/MAINTAINERS.md

@@ -0,0 +1,34 @@
+# Maintainers
+
+Living Atlas is maintained by the Living Atlas maintainers.
+
+## Responsibilities
+
+Maintainers are responsible for:
+
+- keeping the default branch named `main`;
+- protecting local-only security boundaries;
+- rejecting real Logseq graph data, private screenshots, cache snapshots, and local paths in public artifacts;
+- requiring fixture-backed reproduction where possible;
+- keeping release tags, npm package metadata, and docs aligned;
+- reviewing API, cache, adapter, and storage changes against runtime validators and tests.
+
+## Review Expectations
+
+Security, privacy, release, and source-adapter changes need maintainer review before merge. Visual-only changes still need fixture screenshots or UI smoke evidence when they affect the rendered atlas.
+
+Maintainers should prefer small, reviewable changes. Large rewrites should be split by boundary: parser/source adapter, service/cache/API, graph algorithms, renderer, frontend state, docs, or packaging.
+
+## Release Authority
+
+Only maintainers should create public release tags or publish npm packages. A release is eligible only when:
+
+- `npm run validate` passes;
+- `npm run smoke:package` passes;
+- `npm audit --audit-level=moderate` reports no vulnerabilities;
+- `npm run check:public` passes;
+- `npm run check:release` passes from a clean `main` checkout with an exact version tag.
+
+## Private Data
+
+Maintainers should remove or redact public contributions that include real graph files, private screenshots, token URLs, cache snapshots, or machine-specific paths. When private evidence is needed, handle it outside the repository and summarize only the public-safe result.

package/README.md

@@ -0,0 +1,370 @@
+# Living Atlas
+
+Living Atlas turns a local Logseq graph into a read-only, explorable 3D knowledge map. It indexes markdown files from your graph, serves a localhost API, and renders a cinematic Three.js field with clusters, search, focus slices, pathfinding, timeline replay, review flags, and graph-health signals.
+
+The visual goal is science-fiction. The data contract is deliberately boring: every count, label, path, link, and insight must be grounded in the indexed Logseq files.
+
+![Living Atlas fixture demo](docs/assets/living-atlas-demo.png)
+
+All screenshots in this README are generated from the public fixture graph.
+
+## Gallery
+
+| Overview | Source Detail |
+| --- | --- |
+| ![Fixture overview showing the Living Atlas point cloud, local stats, timeline, and cognition stream](docs/assets/living-atlas-demo.png) | ![Fixture source detail showing selected node orbit edges, direct link weights, and atlas filters](docs/assets/living-atlas-source-detail.png) |
+
+| Pathfinder | Connector Radar |
+| --- | --- |
+| ![Fixture pathfinder view showing a traced route from Project Orion to Atlas with alternate paths](docs/assets/living-atlas-pathfinder.png) | ![Fixture connector radar showing a sweep ring and an active connector candidate](docs/assets/living-atlas-radar.png) |
+
+## Contents
+
+- [Try it now](#run-from-github-source)
+- [Run from npm](#run-from-npm)
+- [Use your own Logseq graph](#use-your-own-logseq-graph)
+- [Data and privacy model](#why-trust-it-with-a-graph)
+- [Configuration](#configuration)
+- [Validation](#validation)
+- [Architecture docs](#architecture-docs)
+
+## How To Read The Atlas
+
+- **All** shows the whole indexed graph within the current group, status, confidence, and source filters.
+- **Core** keeps high-signal pages and cluster roots visible without assuming a fixed private ontology.
+- **Active** shows recently changed pages.
+- **Connectors** shows pages that tie otherwise distant graph regions together.
+- **Gaps** shows pages with missing source, weak confidence, missing status, or little trusted context.
+- **Review** shows pages you flagged locally for cleanup.
+- **Timeline replay** filters the graph by page update time so you can watch the visible atlas grow.
+
+Visible group names come from your graph's page types, tags, and inferred clusters. Unknown `source::` values can become filter labels, so use redaction or fixture data for public screenshots.
+
+## Why Trust It With A Graph?
+
+- Local only: the service binds to `127.0.0.1`.
+- Read only: Living Atlas never writes to the Logseq graph.
+- No cloud dependency: rendering and indexing happen on your machine.
+- No Logseq Desktop requirement: the app reads the graph folder directly.
+- No absolute paths in normal API responses: source paths are graph-relative by default.
+- Generated cache, screenshots, and QA artifacts are graph-derived data and are ignored by default.
+
+Do not expose the service through a reverse proxy or remote tunnel unless you add authentication, transport security, and a deployment-specific threat model.
+
+## Requirements
+
+- Node.js `20.19.0` or newer
+- npm
+- A local Logseq graph folder for real data runs
+
+The optional companion MCP server is [`logseq-graph-mcp`](https://github.com/johnschieferleuhlenbrock/logseq-graph-mcp). Use it when agents need guarded read/write access to the same graph. Living Atlas itself remains the read-only visualization and index service.
+
+## Release Status
+
+The `0.1.x` line is the first public release series. It is local-first, read-only against your Logseq graph, and intended for individual desktop use while the adapter and MCP integration surfaces stabilize.
+
+## Run From npm
+
+The npm package ships the built UI and local index service.
+
+Try a public fixture without a Logseq graph:
+
+```bash
+npx logseq-graph-living-atlas --demo
+```
+
+Use your own graph:
+
+```bash
+npx logseq-graph-living-atlas --root /absolute/path/to/your/logseq/graph
+```
+
+Open the `#token=...` app URL printed by the command. Real graph reads are token-protected by default. The demo fixture stays unauthenticated for easy evaluation.
+
+Useful CLI checks:
+
+```bash
+npx logseq-graph-living-atlas --help
+npx logseq-graph-living-atlas --version
+```
+
+After a global install, both `living-atlas` and `logseq-graph-living-atlas` point at the same CLI.
+
+`--root` must point at the graph folder, not the `pages/` folder itself.
+
+## Run From GitHub Source
+
+```bash
+git clone https://github.com/johnschieferleuhlenbrock/logseq-graph-living-atlas.git
+cd logseq-graph-living-atlas
+npm install
+```
+
+### Try The Demo
+
+The demo creates a public-safe fixture graph in the OS user cache at runtime, builds the app, and serves it locally.
+
+```bash
+npm run demo
+```
+
+Open `http://127.0.0.1:8787`.
+
+No demo graph files are committed. Repo-local build and QA artifacts can be removed with:
+
+```bash
+npm run clean
+```
+
+Remove user-cache demo graphs too:
+
+```bash
+npm run clean -- --user-cache
+```
+
+Regenerate the README screenshot from the same fixture data:
+
+```bash
+npm run capture:demo
+```
+
+### Optional MCP Compatibility Smoke
+
+This verifies that the published `logseq-graph-mcp` package and Living Atlas can both read the same generated fixture graph:
+
+```bash
+npm run smoke:mcp
+```
+
+By default the smoke uses `npx logseq-graph-mcp@0.1.2`. To test a local MCP checkout instead:
+
+```bash
+LOGSEQ_GRAPH_MCP_CLI=/absolute/path/to/logseq-graph-mcp/dist/cli.js npm run smoke:mcp
+```
+
+Regenerate the full README gallery:
+
+```bash
+npm run capture:demo -- --gallery
+```
+
+### Use Your Own Logseq Graph
+
+`--root` must point at the graph folder, not the `pages/` folder itself. A valid graph root looks like this:
+
+```text
+my-logseq-graph/
+  pages/
+    Example.md
+  journals/
+    2026_05_31.md
+```
+
+Quick preflight:
+
+```bash
+ls /absolute/path/to/your/logseq/graph/pages
+```
+
+Common macOS locations include `~/Documents`, `~/Library/Mobile Documents`, or a synced folder such as iCloud, Dropbox, or OneDrive. Windows and Linux paths work too; pass the absolute folder that contains `pages/`.
+
+```bash
+npm run build
+npm run serve -- --root /absolute/path/to/your/logseq/graph
+```
+
+Open the token URL printed by the service, usually `http://127.0.0.1:8787/#token=...`.
+
+For split frontend/API development:
+
+```bash
+LIVING_ATLAS_TOKEN=<random-local-token> npm run dev:api -- --root /absolute/path/to/your/logseq/graph --allowed-origin http://127.0.0.1:5177
+npm run dev
+```
+
+Open `http://127.0.0.1:5177/#token=<random-local-token>`.
+
+The Vite dev server proxies `/api` to `127.0.0.1:8787`. Use `--allow-unauthenticated-read` only for trusted local experiments with non-sensitive fixture data.
+
+PowerShell example:
+
+```powershell
+npm run serve -- --root "D:\LogseqGraph" --token "replace-with-a-random-local-token"
+```
+
+## Configuration
+
+You can use command-line arguments, shell environment variables, or Node's env-file support.
+
+```bash
+cp .env.example .env.local
+node --env-file=.env.local server/brain-service.mjs --watch --static dist
+```
+
+Supported settings:
+
+| Setting | Purpose | Default |
+| --- | --- | --- |
+| `LOGSEQ_ROOT` / `--root` | Logseq graph folder | Required |
+| `LIVING_ATLAS_PORT` / `--port` | Local HTTP port | `8787` |
+| `LIVING_ATLAS_CACHE` / `--cache` | Snapshot cache outside the graph | OS user cache directory |
+| `LIVING_ATLAS_TOKEN` / `--token` | Local API token; generated for real graph CLI runs when omitted | Empty in demo mode |
+| `LIVING_ATLAS_REQUIRE_TOKEN=1` / `--require-token` | Require the token for every `/api/*` route | On for CLI real-graph runs |
+| `LIVING_ATLAS_ALLOW_UNAUTHENTICATED_READ=1` / `--allow-unauthenticated-read` | Allow local API reads without a token | Off |
+| `LIVING_ATLAS_ALLOW_UNAUTHENTICATED_REINDEX=1` / `--allow-unauthenticated-reindex` | Allow manual reindex without a token for local development | Off |
+| `LIVING_ATLAS_ALLOWED_ORIGINS` / `--allowed-origin` | Comma-separated local origins allowed to read the API outside same-origin mode | Empty |
+| `LIVING_ATLAS_DEBUG_PATHS=1` / `--debug-paths` | Include absolute diagnostic paths in `/api/health` | Off |
+| `LIVING_ATLAS_MAX_FILES` | Maximum markdown files accepted during ingest | `250000` |
+| `LIVING_ATLAS_MAX_FILE_BYTES` | Maximum bytes per markdown file during ingest | `2097152` |
+
+The service refuses to write its cache inside `LOGSEQ_ROOT`. Cache files are derived graph data; treat them as sensitive unless they were generated from the public fixture.
+
+### Token-Protected Local UI
+
+Real graph runs enable read-token mode by default. Provide a token yourself or use the generated session token printed by the service:
+
+```bash
+npx logseq-graph-living-atlas --root /absolute/path/to/your/logseq/graph --token <your-token> --require-token
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8787/#token=<your-token>
+```
+
+The fragment is not sent in the initial HTTP request. The browser stores it in session storage, strips it from the visible URL, and sends API reads with an `Authorization: Bearer <token>` header. The SSE stream uses the documented `/api/events?token=...` fallback because native `EventSource` cannot send custom headers.
+
+## Logseq Compatibility
+
+Current support:
+
+| Graph area | Status |
+| --- | --- |
+| `pages/**/*.md` | Indexed |
+| `journals/**/*.md` | Indexed |
+| Wikilinks `[[Page]]` | Indexed as graph links |
+| Properties like `type:: project` | Parsed |
+| Typed markdown links like `Owner: [[Page]]` | Parsed |
+| Assets, queries, block refs, and advanced Logseq syntax | Best effort only |
+
+The parser is intentionally isolated and covered by fixture tests, but it is not a full Logseq database implementation.
+
+## API
+
+The service binds to `127.0.0.1` and rejects non-loopback peers. See `docs/API.md` for schemas, query ranges, SSE frames, and error semantics.
+
+```bash
+curl -H "Authorization: Bearer <your-token>" http://127.0.0.1:8787/api/health
+curl -H "Authorization: Bearer <your-token>" "http://127.0.0.1:8787/api/path?from=Atlas&to=Signal%20Desk"
+```
+
+## Keyboard Exploration
+
+The atlas can be driven without leaving the graph field:
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl+K` / `Cmd+K` | Focus command search |
+| `1`..`5` | Switch Whole Mind, Today, Focus, Radar, Replay |
+| `Esc` | Clear the active lens and return to Whole Mind |
+| `Left` / `Right` | Step replay backward or forward while Replay is active |
+
+Endpoints:
+
+- `GET /api/health`
+- `GET /api/snapshot`
+- `GET /api/search?q=<page-or-tag>`
+- `GET /api/focus?q=<page>`
+- `GET /api/node?q=<page>`
+- `GET /api/path?from=<page>&to=<page>`
+- `GET /api/connectors`
+- `GET /api/bridges` deprecated alias for connectors
+- `GET /api/delta`
+- `GET /api/events`
+- `POST /api/reindex`
+
+`POST /api/reindex` requires either `Authorization: Bearer <token>` or `x-living-atlas-token: <token>` unless `--allow-unauthenticated-reindex` is enabled for local development. CLI real-graph runs protect read routes by default; `--allow-unauthenticated-read` is the explicit local-development opt-out.
+
+## Validation
+
+```bash
+npx playwright install chromium
+npm test
+npm run check:runtime
+npm run eval
+npm run test:ui
+npm run test:ui:scale
+npm run check:public
+```
+
+`npm run eval` covers both synthetic 1k/10k/100k graph generation and a 10k-file local service disk/API/reindex path. `npm run test:ui:scale` verifies browser rendering for 10k and budgeted 100k atlas payloads.
+
+For heavier local proof outside normal CI, run the opt-in disk/watch service evaluation:
+
+```bash
+npm run eval:service:100k
+```
+
+Or run the full gate:
+
+```bash
+npm run validate
+```
+
+The UI smoke test uses a generated fixture graph and writes screenshots to a temporary directory unless `LIVING_ATLAS_QA_DIR` is set.
+
+## Repository Policy
+
+Target `main` for all public work. Do not create or target any alternate default branch.
+
+Do not commit real graph data or graph-derived artifacts. These paths are intentionally ignored:
+
+- `.cache/`
+- `dist/`
+- `docs/qa/`
+- `.env`
+- `.env.local`
+- `.public-readiness.local.json`
+
+Contributor validation:
+
+```bash
+npm run clean
+npx playwright install chromium
+npm run validate
+npm audit --audit-level=moderate
+npm pack --dry-run
+npm run smoke:package
+```
+
+Maintainer release validation:
+
+```bash
+npm run clean
+npm run validate
+npm audit --audit-level=moderate
+npm pack --dry-run
+npm run smoke:package
+npm run check:release
+```
+
+For publish rehearsal, `npm pack --dry-run` intentionally runs the production build. Use `npm pack --dry-run --ignore-scripts` only when you want to inspect the package allowlist without regenerating `dist/`.
+
+First publish policy: create a `vX.Y.Z` tag matching `package.json` on `origin/main` and let the protected GitHub Release workflow publish with npm provenance. Emergency manual publish is documented in `docs/RELEASE.md`.
+
+```bash
+git tag v0.1.0
+git push origin main v0.1.0
+```
+
+## Architecture
+
+See `docs/ARCHITECTURE.md`, `docs/API.md`, `docs/ADAPTERS.md`, `docs/REPO_GUIDE.md`, `docs/CONCEPTS.md`, `docs/MCP.md`, `docs/TROUBLESHOOTING.md`, and `docs/RELEASE.md`.
+
+Short version:
+
+- Logseq markdown is the source of truth.
+- The Local Index Service owns parsing, cache, budgets, deltas, and graph APIs.
+- React and Three.js own rendering and interaction.
+- Guarded writes belong in a separate MCP/writeback layer.