apps.siao.ai — nav homepage spec

What this covers: the apps.siao.ai navigation homepage — its scope, stack and testing. Lives in the apps-siao-ai repo, which also holds AnswerHub under /answerhub (a separate spec).

For what is built or deployed, see ClaudeDocs/HANDOFF.md — status deliberately does not live here. No issue tracker exists yet for this project — this file is the spec until one does; move it there once one exists. Full decision trail: NOTES_APPS.md ch.1.

This spec covers only the navigation homepage slice. Migrating the actual ~/Lwopan/learning-platform application logic into /lwopan is explicitly out of scope — see Out of Scope below.

Problem Statement

apps.siao.ai is already listed as a live exit on the siao.ai homepage, but the apps-siao-ai repo behind it has no code — visiting it today resolves to nothing. The owner is building a family of small web apps (starting with a Next.js learning platform currently living at ~/Lwopan/learning-platform, plus future ones) and needs a single place that lists what exists and links to it, rather than each app needing to explain itself or the owner needing to remember raw paths/ports.

Solution

Build a Next.js (TypeScript) site at apps-siao-ai whose homepage renders a list of app cards from a hardcoded, in-repo config array — no database, since this is single-user and not offered to the public for self-service. Each app is mounted as an internal route under the same Next.js app (e.g. apps.siao.ai/lwopan), not a separate subdomain or separate deployment — this keeps future migrated apps under one deploy and one auth/session boundary rather than fragmenting across subdomains. Deployed self-hosted on the same Ubuntu box already running git.siao.ai, reusing its existing Docker Compose + cloudflared + systemd path-watcher auto-deploy chain (see NOTES_GIT_SERVER.md §7–9) rather than Cloudflare Pages, because apps mounted here later (starting with the Lwopan migration) will need a real long-running Node process and a database, not an edge/static runtime.

User Stories

1. As the owner, I want to visit apps.siao.ai and see a list of the apps that exist, so that I have one entry point instead of needing to remember individual URLs.
2. As the owner, I want each app shown as a card with at least a name and short description, so that I can tell apps apart at a glance.
3. As the owner, I want to click an app's card and be taken to that app's route (e.g. /lwopan), so that navigation is a single click.
4. As the owner, I want the app list defined in one place in the codebase (a config array), so that adding or removing an app is a one-line code change with no database or admin UI involved.
5. As the owner, I want the lwopan card to link to /lwopan even before that route has real content, so that the nav layer and the app-migration work can proceed independently — a 404 there today is acceptable and expected, not a bug to fix in this slice.
6. As the owner, I want liquid-glass-toolkit permanently excluded from the list, so that a tool that was explicitly decided against (buggy, over-engineered, "not going to use it") doesn't linger as a visible option that looks live.
7. As the owner, I want the homepage to have its own visual identity distinct from the siao.ai personal homepage (closer to, but simpler than, the planned SiaoHub direction), so that this reads as a functional tools index rather than an extension of the personal page.
8. As the owner, I want the site deployed on the same self-hosted infrastructure as git.siao.ai, using the same push-to-deploy mechanism, so that I don't need to learn or maintain a second deploy pipeline for a second small project.
9. As the owner, I want an automated (Playwright) test suite in place from the very first version of this site, so that regressions in the nav layer are caught even though this code is expected to be substantially rewritten later.
10. As a future session picking up the Lwopan migration, I want the nav homepage and its route structure already in place, so that migrating learning-platform's logic is a matter of filling in /lwopan, not redesigning navigation at the same time.

Implementation Decisions

• Framework: Next.js + TypeScript. Matches learning-platform and other repos in the siao.ai family; avoids running a Next.js project in a non-default JS mode.
• Styling: plain CSS, not Tailwind/shadcn — a deliberate divergence from learning-platform (which already uses Tailwind + shadcn/ui, per its components.json). Reasoning: this frontend is expected to be substantially rewritten once real app migration begins, so investing in a component system now is considered wasted effort. This decision should be revisited, not silently reversed, if that rewrite premise changes.
• Routing/architecture: single Next.js app; each listed tool is an internal route (/lwopan, etc.), not a subdomain and not a separately deployed app. All apps mounted here in the future share this one deploy.
• App list data source: a hardcoded config array/object in code (e.g. apps.config.ts), with at minimum a name, description, and route/href per entry. No database, no admin UI — single-owner use only.
• Homepage content for this slice: exactly one entry, lwopan (temporary name for the eventual Lwopan-derived app; the app will be renamed later, the apps.siao.ai project itself will not). No "coming soon" or disabled state — the card links directly to /lwopan; since that route has no content yet, it resolves as a normal Next.js 404, which is accepted behavior for this slice, not a bug.
• Explicit exclusion: liquid-glass-toolkit (also under ~/Lwopan) is never listed. This isn't "not yet" — it's a permanent exclusion; the Lwopan move is understood as a rewrite/port of chosen logic, not a lift-and-shift of everything under ~/Lwopan.
• Visual design: a distinct visual identity from siao.ai's EB Garamond/ink-paper minimalism — directionally similar to the planned SiaoHub identity (see SPEC_SIAOHUB.md) but scaled down and more functional/utilitarian. No concrete palette or typography chosen yet; that's an implementation detail to settle while building, not a spec-level decision.
• Deployment target: self-hosted, same physical Ubuntu machine as git.siao.ai. Requires: a new Docker Compose service for this app, a new cloudflared ingress rule routing apps.siao.ai to that service, and reuse of the existing systemd path-watcher auto-deploy mechanism (push to apps-siao-ai's main → deploy, no sudo in the chain, mirroring the pattern in NOTES_GIT_SERVER.md §7–9). Not Cloudflare Pages.
• Repo: use the existing apps-siao-ai scaffold repo as-is; no new repo needed.

Testing Decisions

• Good tests here assert on rendered, externally-observable behavior — what's on the page and where links point — not on internal component structure or the shape of the config object.
• Playwright, full suite, from the very first version of this site. This is an explicit owner decision, made against my own recommendation to defer testing given the small scope and expected rewrite — the owner chose to set up automated testing immediately regardless. Don't revisit this by suggesting tests be deferred.
• Modules to test: the homepage render (app cards appear, with correct name/description/href per the config), and the lwopan card's link behavior (navigates to /lwopan; a 404 there is an expected, passing state for this slice — the test should not treat it as a failure).
• Prior art: siao.ai's homepage repo already has a 20-test Playwright suite (see NOTES_HOMEPAGE.md) — follow its conventions (test file layout, how the dev server is started for tests, CI wiring expectations) rather than inventing new ones.

Out of Scope

• Migrating ~/Lwopan/learning-platform's actual functionality (Prisma schema, NextAuth, components, business logic) into /lwopan. This is a distinct, larger piece of future work — deliberately not designed or scheduled here. See NOTES_APPS.md ch.1.
• liquid-glass-toolkit in any form — permanently excluded, not a deferred item.
• Renaming lwopan to its eventual real name — deferred so it doesn't block this slice; not part of this spec.
• Any database, admin UI, or self-service mechanism for managing the app list — explicitly rejected in favor of a hardcoded config.
• Auth/login on the nav homepage itself — not requested; the homepage is a public-facing (if unlisted) index, same trust model as siao.ai's homepage.
• Finalized visual design (exact palette, typography, layout system) — direction is set (SiaoHub-adjacent but simpler) but not specified to the pixel level here.
• Setting up the actual server-side infra (Docker Compose file, cloudflared ingress config) — this spec states the deployment target and mechanism; the concrete config files are implementation work.

Further Notes

• OVERVIEW.md and (until just now) HANDOFF.md describe the self-hosted server as Debian 12; it's actually Ubuntu. Corrected in HANDOFF.md and noted in NOTES_APPS.md ch.1 — if any other doc still says Debian, treat it as stale.
• The owner corrected a mid-session mix-up: it's the lwopan app that will be renamed later, not the apps.siao.ai project. Keep these separate in any future naming discussion.
• No issue tracker or triage-label vocabulary was available for this project (same situation as SiaoHub) — this spec stays as a file in ClaudeDocs/ until one exists.