Rewrite README for readers; move maintenance notes to MAINTENANCE.md

README now focuses on what the docs cover, how to read them, and how to
contribute via the per-article edit/issue links. All operational content
(commands, base-path notes, layout, publish flow) moved to
MAINTENANCE.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

MAINTENANCE.md

@@ -0,0 +1,82 @@
+# Maintenance
+
+Operational notes for maintainers of the Paperclip docs site. Reader-facing instructions live in [README.md](README.md).
+
+## Repo layout
+
+```
+docs/
+├── docs-website/        # Static site shell + release builder
+│   ├── index.html       # Main SPA (routing, rendering, TOC, search)
+│   ├── nav.json         # Section/page manifest — source of truth for sidebar & landing
+│   ├── build-release.mjs  # Produces a standalone bundle in .site/
+│   ├── preview.html     # Legacy preview entry (kept for compatibility)
+│   └── v1.html          # Archived v1 snapshot
+├── user-guides/         # Guide pages + screenshots/{light,dark}
+├── api/                 # API reference Markdown
+├── cli/                 # CLI reference Markdown
+├── adapters/            # Adapter docs & catalogue
+├── deploy/              # Self-hosting & ops docs
+└── guides/              # Misc long-form guides
+scripts/
+└── publish-gh-pages.sh  # Builds and pushes to the gh-pages branch
+.github/ISSUE_TEMPLATE/   # Support / bug / docs-feedback templates
+```
+
+## Commands
+
+```sh
+# Build the static site into .site/ using the GitHub Pages base path
+npm run docs:build
+
+# Build with auto base-path detection (useful when serving from the repo root locally)
+npm run docs:build:auto
+
+# Serve .site/ on http://localhost:4321/
+npm run docs:serve
+
+# Build and push to the gh-pages branch
+npm run docs:publish
+```
+
+## Base paths
+
+`build-release.mjs` accepts `--base-path <path|auto>`:
+
+- **GitHub Pages** — use `/paperclip-docs/` (the default in `docs:build`).
+- **Local preview** — use `auto` (`docs:build:auto`). Paths resolve relative to `index.html`, so the site works under any prefix (or none).
+- **Self-hosting under a different prefix** — pass an explicit path, e.g. `--base-path /docs/`.
+
+Mismatched base paths are the most common cause of 404s after a build — if asset URLs point to `/paperclip-docs/...` but you serve at `/`, everything breaks.
+
+## Adding or moving pages
+
+1. Create the Markdown file in the appropriate `docs/<section>/` folder.
+2. Register it in `docs/docs-website/nav.json` under the correct section. The `file` field is relative to `docs/docs-website/` (typically `"../<section>/<page>.md"`).
+3. Page titles, section grouping, and sidebar order all derive from `nav.json`. There is no filesystem-based auto-discovery.
+4. Slugs are derived from the file path — `user-guides/guides/foo.md` becomes `/#/foo`, other sections keep their path.
+
+## Screenshots
+
+Store UI captures under `docs/user-guides/screenshots/{light,dark}/<name>.png`. The renderer automatically swaps the correct theme variant at runtime based on the user's current theme. Always provide both.
+
+## Per-article feedback links
+
+Every article ends with "Suggest an edit" and "Report an issue" links. These are generated in `loadPage()` in `docs/docs-website/index.html` and point at:
+
+- `github.com/aronprins/paperclip-docs/edit/main/<path>` — GitHub web editor.
+- `github.com/aronprins/paperclip-docs/issues/new?template=03-docs-feedback.yml&...` — prefilled docs-feedback issue.
+
+If the repo is ever renamed or mirrored, update `DOCS_REPO_SLUG` / `DOCS_REPO_BRANCH` constants near the top of `appendPageFeedback()`.
+
+## Issue templates
+
+`.github/ISSUE_TEMPLATE/` holds three templates:
+
+- `01-support.yml` — end-user support questions.
+- `02-bug.yml` — bug reports against the docs site itself (not product bugs).
+- `03-docs-feedback.yml` — referenced by the per-article "Report an issue" link. The `docs_page` field id must stay in sync with the URL param emitted in `appendPageFeedback`.
+
+## Publishing
+
+`scripts/publish-gh-pages.sh` clones the repo into a tempdir, checks out (or creates) `gh-pages`, replaces its contents with a fresh build, commits, and pushes. It leaves the working tree untouched, so it's safe to run with uncommitted changes. A `.nojekyll` marker is added so GitHub Pages serves files whose names start with `_`.

README.md

@@ -1,40 +1,33 @@
-# paperclip-docs
+# Paperclip Docs
 
-Lean source repo for the Paperclip documentation site.
+Source for the [Paperclip](https://github.com/paperclipai/paperclip) documentation site — user guides, API and CLI reference, adapter docs, and deployment notes.
 
-## Commands
+**Read the docs:** https://aronprins.github.io/paperclip-docs/
 
-Build the static site into `.site/`:
+## What's inside
 
-```sh
-npm run docs:build
-```
+- **Guides** — Getting started, core concepts, and day-to-day usage.
+- **API reference** — Control-plane endpoints and payload schemas.
+- **CLI reference** — `paperclip` command surface.
+- **Adapters** — Plugin authoring and the integrations catalogue.
+- **Deploy** — Self-hosting, upgrades, and operational guidance.
 
-Preview the built site locally:
+The site is a single static shell that renders the Markdown files in `docs/` directly — no framework, no build step required to read the raw pages.
 
-```sh
-npm run docs:serve
-```
+## Contributing
 
-Publish the current site to `gh-pages`:
+Spotted a typo, a broken link, or something that could be clearer? There are two easy paths, both linked from the footer of every docs page:
 
-```sh
-npm run docs:publish
-```
+- **Suggest an edit** — opens the underlying Markdown file in GitHub's web editor. Make the change and submit a PR without leaving the browser.
+- **Report an issue** — opens a prefilled [Docs feedback](.github/ISSUE_TEMPLATE/03-docs-feedback.yml) issue with the page URL already attached.
 
-## Repo Layout
+For larger changes, fork the repo and open a PR against `main`. Screenshots live under `docs/user-guides/screenshots/{light,dark}/` and should be provided in both themes when replacing UI captures.
 
-- `docs/docs-website/`
-  Static site shell, navigation manifest, and release builder.
-- `docs/user-guides/`
-  User-facing guide pages and screenshots.
-- `docs/adapters/`
-  Adapter documentation.
-- `docs/api/`
-  API reference pages.
-- `docs/deploy/`
-  Deployment documentation.
-- `docs/cli/`
-  CLI reference pages.
-- `scripts/publish-gh-pages.sh`
-  Local publish script for GitHub Pages.
+## Community
+
+- [Discord](https://discord.gg/m4HZY7xNG3)
+- [GitHub Discussions](https://github.com/paperclipai/paperclip/discussions)
+
+## License
+
+Docs content is released under the same license as the Paperclip project. See the main [paperclip](https://github.com/paperclipai/paperclip) repository for details.