chore: propagate main into development

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Deploy docs site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs-site/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs-site
+        run: npm ci
+
+      - name: Build
+        working-directory: docs-site
+        run: npm run build
+
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          path: docs-site/build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.2"
+  ".": "0.5.0"
 }

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0](https://github.com/Wikid82/Hestia/compare/v0.4.2...v0.5.0) (2026-09-16)
+
+
+### Features
+
+* docs site (Docusaurus) with quick start, features, troubleshooting, FAQ ([b2ef01c](https://github.com/Wikid82/Hestia/commit/b2ef01c7ba0c2950bc9cf730ce7eb391e8289a77))
+
 ## [0.4.2](https://github.com/Wikid82/Hestia/compare/v0.4.1...v0.4.2) (2026-09-07)
 
 

CLAUDE.md

@@ -192,6 +192,15 @@ adding a new external dependency) before just doing it.
   it does) in the same change. `.env.example` points to that doc rather
   than explaining each variable inline, so don't let the two drift —
   a variable missing from either one is a bug.
+- Keep `docs-site/docs/` (the published GitHub Pages site, built by
+  `.github/workflows/docs.yml`) in sync with any user-facing change —
+  new/changed features, env vars that affect setup, new troubleshooting
+  cases. Update the relevant page (`features.md`, `quick-start.md`,
+  `troubleshooting.md`, `faq.md`) in the same PR, not as a follow-up —
+  same "don't let it drift" reasoning as the `.env.example`/
+  `docs/environment.md` pairing above. This is distinct from `docs/` at
+  the repo root, which holds internal working docs (`current_spec.md`,
+  `environment.md`) rather than published site content.
 
 ## Definition of Done
 
@@ -238,6 +247,12 @@ Every PR is expected to clear this bar before it's mergeable — not just
   `docker-build.yml`. golangci-lint is advisory in CI
   (`continue-on-error: true`) since it's already blocking locally via
   lefthook.
+- **Docs updated for anything user-facing.** A PR that adds or changes
+  behavior a self-hoster would notice (a new feature, a changed setup
+  step, a new failure mode worth documenting) isn't done until the
+  matching `docs-site/docs/` page reflects it — see the Conventions note
+  above. A PR with no user-facing change (internal refactor, CI tweak,
+  dependency bump) doesn't need a docs update just to check a box.
 
 ## Subagents
 

docs-site/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs-site/README.md

@@ -0,0 +1,15 @@
+# Hestia docs site
+
+Built with [Docusaurus](https://docusaurus.io/). Published to GitHub Pages
+by `.github/workflows/docs.yml` on every push to `main` that touches this
+directory.
+
+```bash
+npm install
+npm start      # local dev server with hot reload
+npm run build  # production build to ./build, what the workflow deploys
+```
+
+Content lives in `docs/` — see `sidebars.ts` for page order. Per
+[`CLAUDE.md`](../CLAUDE.md)'s Definition of Done, these pages should be
+updated in the same PR as any user-facing change, not as a follow-up.

docs-site/audit-ci.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://raw.githubusercontent.com/IBM/audit-ci/main/docs/schema.json",
+  "high": true,
+  "allowlist": []
+}

docs-site/docs/faq.md

@@ -0,0 +1,68 @@
+---
+id: faq
+title: FAQ
+description: Frequently asked questions about Hestia.
+---
+
+# FAQ
+
+### How is Hestia different from Sweepy?
+
+Sweepy (and similar tools) is subscription SaaS — you pay monthly and your
+family's data lives on their servers. Hestia is free, MIT-licensed, and
+self-hosted: you run it on your own server, NAS, or Raspberry Pi, and your
+data never leaves your infrastructure.
+
+### Does Hestia require an account or cloud service?
+
+No. Hestia is fully self-hosted — there's no external account, license
+server, or telemetry requirement. The only outbound network dependency is
+optional SMTP for sending invite emails, which you configure yourself if
+you want it.
+
+### Can multiple families share one Hestia instance?
+
+Yes. One instance can host several independent households with no
+cross-visibility between them — see [Features](./features.md#multi-household)
+for details. A self-hoster can invite a friend or relative to run their
+own separate household on the same instance without either household
+seeing the other's data.
+
+### Do kids need their own email address to use Hestia?
+
+No. A "managed profile" has no login credentials of its own — it's
+switched into via a Netflix-style avatar picker on a shared/kiosk screen,
+optionally protected by a PIN. A managed profile can get its own
+email/password login added later if desired.
+
+### Is my data backed up automatically?
+
+Hestia uses SQLite, so your entire household's data is one file
+(`./data/hestia.db` in the default Docker setup). Back up that file with
+whatever backup tooling you already use for your server — Hestia doesn't
+ship its own backup scheduler.
+
+### What happens if I lose the first admin account?
+
+There's currently no built-in "recover the very first admin" flow beyond
+normal password-reset (email/password logins can use forgot-password if
+SMTP is configured). If you're testing without SMTP configured and lock
+yourself out, you'll need direct database access to recover — see the
+[Troubleshooting](./troubleshooting.md) page for related setup issues.
+
+### Is Hestia production-ready?
+
+Hestia is early days — actively developed, with core features landing
+incrementally. Check the
+[GitHub repository](https://github.com/Wikid82/Hestia) for current status
+before relying on it for anything critical.
+
+### How do I report a bug or request a feature?
+
+Open an issue on [GitHub](https://github.com/Wikid82/Hestia/issues).
+
+### Can I contribute?
+
+Hestia is MIT-licensed and open to contributions. See the
+[GitHub repository](https://github.com/Wikid82/Hestia) for the current
+codebase and conventions.

docs-site/docs/features.md

@@ -0,0 +1,77 @@
+---
+id: features
+title: Features
+description: What Hestia does today and what's planned for v1.
+---
+
+# Features
+
+Hestia is under active development — this page reflects the current state
+honestly, including what's planned but not yet built. See the
+[GitHub repository](https://github.com/Wikid82/Hestia) for up-to-date
+progress.
+
+## Multi-household
+
+One Hestia instance can host several independent households with no
+cross-visibility between them. A self-hoster running their own family's
+chart can also invite a friend who doesn't want to self-host — that friend
+gets their own fully separate household on the same instance, with no
+access to anyone else's data.
+
+## Roles
+
+Two independent things, not a tier ladder:
+
+- **Head of Household (HoH)** — full control of their own household
+  (members, chores, invites). Scoped to one household only.
+- **System admin** — a separate, instance-wide flag independent of
+  household membership. Grants cross-household administration, like
+  inviting new HoHs or managing instance-wide notification settings. The
+  first-ever signup on a fresh instance gets both roles automatically —
+  that's the self-hoster who owns the instance.
+
+## Flexible logins per person
+
+Any profile can have its own email + password and log in directly — not
+just one shared household login. A profile without one (a "managed
+profile," e.g. a kid without an email address) is switched into locally
+via a Netflix-style avatar picker on a shared/kiosk screen, optionally
+PIN-gated. Either path works for any profile, and a managed profile can
+get its own login set up later.
+
+## Invite-based membership
+
+Joining a household you weren't the first signup on always happens by
+invite — a system admin invites a new HoH (who gets their own independent
+household), or a HoH invites a member of their own household by email.
+Open public self-signup is off by default and can be enabled by the
+instance operator.
+
+## Recurring, assignable, or open chores
+
+- Chores can repeat daily, weekly, on weekdays, or on a custom schedule.
+- A chore can be assigned to a specific household member, or left open for
+  anyone in the household to claim.
+- Completing a chore awards points.
+
+## Points and streaks
+
+Points and streaks are the gamification layer for v1 — deliberately kept
+simple. Hestia is a chore chart, not a game.
+
+## Realtime sync
+
+One profile completing a chore updates another profile's view live, so a
+shared kitchen tablet and a parent's phone stay in sync without a manual
+refresh.
+
+## Self-hosted by design
+
+- **No account or cloud requirement** — runs entirely on your own
+  server/NAS/Raspberry Pi.
+- **SQLite** — the whole app backs up by copying one file.
+- **Docker image built for amd64 and arm64** — Raspberry Pi and ARM NAS
+  friendly.
+- **No background jobs** — chore due-dates are computed on read, not via a
+  scheduler, keeping the deployment footprint minimal.

docs-site/docs/index.md

@@ -0,0 +1,47 @@
+---
+id: index
+title: Hestia
+description: A free, self-hosted, family-focused chore chart — no subscription, no cloud account, your data stays on your own server.
+slug: /
+---
+
+# Hestia
+
+Hestia is a **self-hosted, family-focused household chore chart**. Add
+chores, assign them to a specific person or leave them open for anyone in
+the household to claim, check them off, and earn points — no subscription,
+no cloud account, your data stays on your own server.
+
+## Why Hestia exists
+
+Most tools people find when they search for a chore chart app fall into
+one of two buckets:
+
+- **Subscription SaaS** (e.g. [Sweepy](https://sweepy.app)) — recurring
+  cost for something as simple as a household chore list, and your
+  family's data lives on someone else's server.
+- **General-purpose task trackers** (Todoist, Trello-style boards, etc.)
+  repurposed for a use case they weren't designed for — built for software
+  teams, not a shared family screen on the fridge.
+
+Hestia is built specifically for the self-hosted community: free,
+[MIT-licensed](https://github.com/Wikid82/Hestia/blob/main/LICENSE), and
+simple enough that a non-technical family member can use it from a
+wall-mounted tablet without any onboarding.
+
+## Where to go next
+
+- **[Quick start](./quick-start.md)** — get a running instance in a few
+  minutes with Docker.
+- **[Features](./features.md)** — what Hestia does today and what's
+  planned for v1.
+- **[Troubleshooting](./troubleshooting.md)** — fixes for common
+  self-hosting friction (env vars, ports, permissions).
+- **[FAQ](./faq.md)** — positioning, licensing, and data-ownership
+  questions.
+
+## Project status
+
+Hestia is early days — actively developed, not yet a polished v1. See the
+[GitHub repository](https://github.com/Wikid82/Hestia) for current
+progress, open issues, and the changelog.