freeshard

Load-bearing design decisions, invariants, and honest weak points of shard_core. Use BEFORE changing anything that touches auth, routing, startup/shutdown order, app status handling, signals, caching, or paths. TRIGGER on "why is there no auth on this route", "add an endpoint", "add a status", "app not starting", edits to app_factory.py, web/internal/auth.py, traefik_dynamic_config.py, app_tools.py, app_lifecycle.py, signals.py, or any question about path_root vs path_root_host, JWT, forwardAuth, or what survives a restart. SKIP for step-by-step how-to-run instructions (use freeshard-run-and-operate), config option catalogs (use freeshard-config-and-flags), protocol theory (use freeshard-domain-reference), or debugging a live symptom (use freeshard-debugging-playbook).

Set up and verify a working shard_core development environment. Use when starting from a fresh clone or bare machine, creating a git worktree for an issue, running uv sync, wondering what a justfile recipe does (run-dev, cleanup, get-types, set-version, run-from-backup), reading the Dockerfile, or hitting env-shaped failures (import errors, "config.toml not found", pytest can't bind port 5433, docker network 'portal' already exists, black/ruff not found). TRIGGER on: "set up the repo", "uv sync", ".worktrees", "justfile", "just cleanup", "Dockerfile", "CI installs differently than local", fresh-environment smoke test. SKIP when: actually running the shard or the compose stack, dev server usage, backup/restore ops (use freeshard-run-and-operate); writing or debugging tests and fixtures (use freeshard-testing-and-qa); type-sync policy and controller drift details (use freeshard-ecosystem-contracts); config keys and env-override semantics (use freeshard-config-and-flags).

Catalog of every shard_core configuration axis and how overrides actually work. Use when adding/changing/reading a config option, wiring a FREESHARD_* env var, editing config.toml / local_config.toml / tests/config.toml / .env.template / docker-compose.yml environment mappings, checking whether a feature flag exists, or debugging 'my override does nothing' / 'Settings() crashes at boot'. TRIGGER on shard_core/settings.py, pydantic-settings, env_nested_delimiter, FREESHARD_ env vars, DISABLE_SSL, telemetry.enabled, apps.pruning, settings_override, config_override. SKIP when the question is about running/deploying the stack (use freeshard-run-and-operate), test fixture design beyond config overrides (use freeshard-testing-and-qa), or why a config decision was made (use freeshard-architecture-contract).

How to MEASURE things in the freeshard (shard_core) repo instead of eyeballing them: runnable scripts for type-drift vs the controller, env-override proof, todo scanning, hung-test cleanup, and churn/fix hotspots; plus techniques for fd headroom, OOM-vs-crash discrimination, on-the-wire proxy inspection, disk-space semantics, and GH board/issue queries that actually work. TRIGGER on: 'is the backend type copy stale', 'did my FREESHARD_* env var take effect', 'find todos', 'un-wedge hung test infra' (for the symptom itself — tests won't start — see freeshard-testing-and-qa first), 'which files are bug hotspots', 'measure fd headroom', 'discriminate OOM-kill from self-abort', 'capture what the proxy actually sends', 'disk_space_low semantics', 'query the Dev Board', 'gh issue view fails with projectCards', profiling with yappi. If all you have is a raw symptom string (a 'too many open files' loop, a crashing container), load freeshard-debugging-playbook first. SKIP when: you are diagnosing a specific known fail

Maintaining Freeshard's docs of record (agents.md, README.md, docs.freeshard.net) and writing anything user- or public-facing. TRIGGER on editing agents.md or README.md, "update the docs", "is this doc still true", contradictions between a doc and the code, the Portal/Freeshard naming question ("should I rename portal to shard?"), portal_controller.py vs freeshard_controller.py confusion, writing PR descriptions/commit messages/release notes, or any external claim about what Freeshard is or does. SKIP when the task is the mechanics of config options (use freeshard-config-and-flags), cross-repo type-sync (use freeshard-ecosystem-contracts), release *execution* (use freeshard-run-and-operate), or change gating/review policy (use freeshard-change-control).

Theory pack for shard_core's protocols and standards AS APPLIED HERE — HTTP Message Signatures (RSA-PSS), shard ID / short_id derivation, Traefik forwardAuth + errors middleware + DNS-01 wildcard ACME, terminal JWT pairing, rclone crypt backups, compose-file-per-app orchestration, yoyo + psycopg3 transaction semantics, Pydantic v2 idioms. TRIGGER on "how does peer/signature auth work", "key_id / short_id / shard id", edits to shard_core/service/{crypto,signed_call,peer,pairing,backup,traefik_dynamic_config}.py, data/traefik.yml, migrations/, shard_core/settings.py, app_meta versioning, X-Forwarded-* / X-Ptl-* headers, "forwardAuth protocol mechanics" (for "why is there no auth on this route", use freeshard-architecture-contract), rclone flags, "where do transactions commit". SKIP when you need step-by-step failure triage (use freeshard-debugging-playbook), running/deploying the stack (freeshard-run-and-operate), config-key catalogs (freeshard-config-and-flags), cross-repo type sync (freeshard-ecosystem-contra

Running, deploying, and operating shard_core. Use when you need to start the app (dev server or full docker compose stack), pair a first device, find where data lands on disk (FREESHARD_DIR/core, user_data, postgres_data), run or restore a backup, cut a release, or understand hosted-vs-self-hosted behavior. TRIGGER on: 'just run-dev', 'docker compose up', .env / .env.template, pairing code, welcome log, FREESHARD_DIR, rclone / backup / restore / download_backup.sh, 'just set-version', release checklist, ghcr.io image tags, 'is this fix deployed?', self-hosting, Let's Encrypt / DISABLE_SSL. SKIP when: editing config values or env-override mechanics (use freeshard-config-and-flags), setting up the Python dev environment / uv / worktrees (use freeshard-build-and-env), writing or running tests (use freeshard-testing-and-qa), diagnosing a live failure (use freeshard-debugging-playbook), or changing CI workflows themselves (use freeshard-change-control).

How to run, write, and trust tests in the freeshard (shard_core) repo. Use when running pytest, adding or modifying tests, choosing between the api_client/app_client/db fixtures, overriding config in tests, diagnosing a flaky or hanging test, or deciding what evidence a fix needs before a PR. TRIGGER on: 'run the tests', 'add a test', tests/conftest.py, tests/util.py, pytest-docker, LifespanManager, 'test hangs', 'CI-only failure', 'flaky test', port 5433, 'docker network portal', wait_until_app_installed, TimeoutError in CI. SKIP when: recreating the dev environment / uv sync / worktrees (use freeshard-build-and-env), debugging production behavior rather than tests (use freeshard-debugging-playbook), editing .github/workflows themselves (use freeshard-change-control for gates; this skill only describes what CI runs), or cataloguing config options outside tests (use freeshard-config-and-flags).

How changes get accepted into the Freeshard shard_core repo: issue triage on the Dev Board, agent pickup/handback signals, branch & PR conventions, the non-negotiables (Max-merge-only, stay on Traefik v2, no shell on shards, DO-NOT-MODIFY synced types), and release discipline (merged is NOT shipped). Use when starting work on a GitHub issue, opening a PR, deciding whether something needs an issue/spec/sign-off, or asking 'is this fix actually released?'. TRIGGER on: picking up an assigned issue, 'open a PR', 'is this shipped', 'bump the version', 'release this', 'Needs Intent', Dev Board / project board queries, Traefik version questions, edits under shard_core/data_model/backend/. SKIP when you need the mechanical release/run commands themselves (freeshard-run-and-operate), test-writing rules (freeshard-testing-and-qa), cross-repo type-sync mechanics (freeshard-ecosystem-contracts), or the history of why a past fix was rejected (freeshard-failure-archaeology).

Symptom-to-triage playbook for known Freeshard shard_core failure modes. Use when diagnosing a live or reported failure: shard up but unreachable, "too many open files" in traefik logs, all controller writes return 422, app won't start / container name conflict / stale network, backup failures or rclone errors, burst 500s on app access, Immich thumbnails broken or postgres crash-looping, app stuck INSTALLATION_QUEUED, config override silently ignored, OOM kills / restart loops. TRIGGER on incident reports, "shard unreachable", "backups failing", "app stuck", error strings like EMFILE, 422 Unprocessable, "already in use", PANIC, SIGABRT. SKIP when writing new tests or diagnosing test flakiness (use freeshard-testing-and-qa), when you need measurement tooling (use freeshard-diagnostics-and-tooling), or when researching WHY the design is this way (use freeshard-architecture-contract or freeshard-failure-archaeology).

Chronicle of every major Freeshard incident, dead-end branch, rejected fix, and revert — so you never re-fight a settled battle. TRIGGER when starting work that touches backup/rclone, TinyDB/Postgres/storage, Docker lifecycle (stale containers/networks, python-on-whales), Traefik/proxy/call_backend, splash screens, releases/CI, or when you wonder "has this been tried before?", "why is this code weird?", "why is this PR/branch abandoned?". Also TRIGGER before resurrecting any unmerged branch or closed PR. SKIP when you need live-symptom triage steps (use freeshard-debugging-playbook), design rationale for current architecture (use freeshard-architecture-contract), or release/merge procedure (use freeshard-change-control).

Executable, decision-gated campaign to productionize the embedded OIDC identity provider inside shard_core (Authlib), replacing the rejected Authelia direction. TRIGGER on: OIDC, OpenID Connect, SSO, single sign-on, identity provider, IdP, Authlib, authorization code, PKCE, id_token, JWKS, discovery document, redirect_uri, 'zero-click login', Immich login, spike/oidc-provider-poc, shard_core/service/oidc_provider.py, shard_core/web/public/oidc.py, tests_poc/, Authelia, PR #86, issue #36, 'pairing session bridge'. SKIP when the task is about the existing terminal-pairing JWT auth or Traefik forwardAuth as-is (use freeshard-domain-reference), general auth debugging (freeshard-debugging-playbook), or generic release mechanics (freeshard-change-control).

First-principles analysis recipes for the Freeshard repos — how to PROVE a root cause instead of pattern-matching to the first plausible fix. Use when only a subset of shards/requests fails, when two components disagree about the same bytes, when a formula is duplicated across languages, when adding per-request DB/IO work, when a container "looks OOM-killed", when a guard/sentinel exists and you must say what it protects, when optimizing cloud cost, or before running any discriminating experiment. TRIGGER on "root cause", "why does only X fail", "prove the mechanism behind this failure class (fd exhaustion, pool exhaustion, proxy write rejection, kill loops)", "rounding mismatch", "prices disagree", "Azure cost", "migration never ran", "prove it". If you only have the raw symptom string (an EMFILE loop, a 422, an OOM-looking restart loop), load freeshard-debugging-playbook first. SKIP when you need the symptom→triage lookup table for a KNOWN failure mode (use freeshard-debugging-playbook), the history of a sp

Open research problems where Freeshard can advance the state of the art, led by the personal-agent-on-shard bet ('your apps are your agent's tools and memory'). Use when asked to explore, prototype, or evaluate frontier work: agent apps on shards, always_on apps, public webhook paths, apps-as-principals token scoping, invisible self-hosting UX, cold-start/PAUSED-PAGED economics (#81/#109/#26), or the self-developing-repo loop. TRIGGER on: 'agent app', 'AI on the shard', 'always_on', 'moat', 'Olares', 'Letta', 'Goose', 'personal agent', 'research direction', 'what makes Freeshard different', 'cold start', 'PAUSED tier', RFC issues #81 #109 #110 #26. SKIP when implementing the OIDC provider itself (use freeshard-oidc-identity-campaign), when doing routine issue work (freeshard-change-control), when you need auth/crypto theory (freeshard-domain-reference), or evidence/method discipline (freeshard-research-methodology).

The discipline that turns a hunch into an accepted result in the Freeshard project — evidence bar, idea lifecycle, documented retirement, where good ideas come from, and which artifact to write when. TRIGGER on "how do I propose X", "should I spike this", "is this hypothesis proven", "why did they reject/close/abandon Y", "where do ideas get decided", writing a root-cause analysis, closing an investigation, deciding between spike branch vs issue vs PR, or handling a vague issue. SKIP when you need the mechanics of the change pipeline (gates, review, release — use freeshard-change-control), the chronicle of a specific past investigation (use freeshard-failure-archaeology), or concrete measurement recipes (use freeshard-proof-and-analysis-toolkit).