Phase 1: content source of truth — 40 documents across six areas
Satisfies the Phase 1 Definition of Done: - content/ validates cleanly against the frozen schema. `make validate` reports OK: 40 document(s) validated, 0 violations. - Six areas exist, each with an L1 entry: ai-overview, platform-overview, edge-overview, products-overview, history-overview, about-overview. - All six areas have an L2 entry: ai-systems, platform-estate, edge-fleet, products-business, history-engagements, about-narrative. - 28 L3 artefact stubs under content/<area>/l3/. Every artefacts[].url in every document resolves to one of them; the validator proves there are no dangling references (and a deliberately broken copy exits 1). - Every metric value traces to a source line in the evidence notes or the approved metric set in reference/content-map.md (per-metric citations are recorded in the AUD-131 completion comment). - Every document carries confidence and last_verified=2026-10-26; the validator rejects a missing or non-canonical value. - docs/content-redaction.md records the redaction pass: identifiers, third party personal data, credentials and infrastructure detail excluded, with reasons, plus the two numbers that are reported rather than smoothed. Honesty positions held: 3 businesses active (12 adoptions over time), Where-Woof deployed and pre-market, failures kept in (edge-failures), no promotion of in-progress work to delivered. No site code, no templates, no CSS, no rendering (Phase 2).
This commit is contained in:
Documenter
35
content/platform/l3/platform-backups.md
Normal file
35
content/platform/l3/platform-backups.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
id: platform-backups
|
||||
area: platform
|
||||
level: 3
|
||||
title: "Artefact — Backups and restore runbook"
|
||||
claim: "Three tiers — local snapshots · a copy on another machine · an offsite copy — with retention stated in the job and a restore runbook kept beside them."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Borg, Kopia, Backrest, AWS S3, systemd, NFS]
|
||||
metrics: [{label: "backup tiers", value: 3}, {label: "retention windows in the primary job", value: 3}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, backups, restore, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Backups and restore runbook
|
||||
|
||||
**Status: stub.** Redacted job definitions and the restore runbook land in Phase 7. Passphrase locations and remote paths are removed before publication.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The backup design: Borg jobs on the two desktop hosts to local storage with a network copy, Kopia and Backrest on the edge host to network storage, an offsite copy in object storage, and retention expressed in the job (seven daily, four weekly, three monthly, plus annual on the edge). Beside it, the restore runbook and the list of what is deliberately not covered.
|
||||
|
||||
## What it proves
|
||||
|
||||
That failure was designed for: three tiers cover disk loss, machine loss and site loss, and the restore path is written down rather than recovered from memory at the worst possible moment.
|
||||
|
||||
## Limits stated on the page
|
||||
|
||||
Not everything is covered, and the page says so — one storage host is itself a single point of failure for some repositories, and the file server has no backup of its own. Those are known gaps with owners, not oversights to be hidden.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. Source: the infrastructure reference and the backup system notes, read 2026-10-26.
|
||||
31
content/platform/l3/platform-containers.md
Normal file
31
content/platform/l3/platform-containers.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: platform-containers
|
||||
area: platform
|
||||
level: 3
|
||||
title: "Artefact — Container inventory"
|
||||
claim: "Fifty or more containers across the estate — each with its own port · its own folder · and a memory cap equal to its swap cap."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Docker, Compose, Caddy, Proxmox]
|
||||
metrics: [{label: "containers in the estate", value: 50}, {label: "memory cap rule", value: "mem_limit equals memswap_limit"}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, docker, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Container inventory
|
||||
|
||||
**Status: stub.** A digest of the inventory — grouped by purpose, with addresses removed — lands in Phase 7.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The inventory generated from the hosts, grouped by purpose: media and file services, home automation, the AI services, the public edge, and the build tooling. For each service the same three facts are recorded — port, configuration folder, memory cap.
|
||||
|
||||
## What it proves
|
||||
|
||||
That the estate is inventoried rather than accumulated, and that the resource rules are applied per service instead of being a policy on a wiki page.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7, generated from the live hosts. Counts follow the approved metric set; the exact number is regenerated at capture time.
|
||||
31
content/platform/l3/platform-network.md
Normal file
31
content/platform/l3/platform-network.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: platform-network
|
||||
area: platform
|
||||
level: 3
|
||||
title: "Artefact — Network layout and remote access"
|
||||
claim: "A private mesh and SSH everywhere · services bound to loopback · and one public listener at the edge terminating TLS for the sites that are allowed to be seen."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [Tailscale, SSH, Caddy, DNS, Termux]
|
||||
metrics: [{label: "public listeners per service", value: 1}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, networking, security, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Network layout and remote access
|
||||
|
||||
**Status: stub.** The topology diagram lands in Phase 7 with addresses and hostnames redacted.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The layout: hosts on a private mesh for remote access, SSH on every machine, a phone used as a terminal, and an edge host that terminates TLS and proxies to loopback-bound services. New services bind to loopback by default; making something public is an explicit edge change, not a side effect of starting a container.
|
||||
|
||||
## What it proves
|
||||
|
||||
Security posture chosen rather than inherited: no service is reachable because it happened to bind to all interfaces, and there is exactly one place where the outside world meets the estate.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. Internal addressing, hostnames and public DNS names are excluded from publication by the redaction pass.
|
||||
35
content/platform/l3/platform-nixos.md
Normal file
35
content/platform/l3/platform-nixos.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
id: platform-nixos
|
||||
area: platform
|
||||
level: 3
|
||||
title: "Artefact — Declarative multi-host configuration"
|
||||
claim: "Machines are described rather than assembled — a shared NixOS base · a replicated desktop and terminal · and Proxmox underneath the virtualised side."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [NixOS, Niri, Proxmox, Neovim, Zsh, Ghostty]
|
||||
metrics: [{label: "hosts on the declarative base", value: 4}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, nixos, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Declarative multi-host configuration
|
||||
|
||||
**Status: stub.** A redacted excerpt of the configuration tree lands in Phase 7. No hostnames, addresses or keys are published.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The shape of the configuration: one shared base, per-host modules, and the parts that make the desktop and the terminal identical everywhere — window manager, editor, shell and the plugins that carry the work. Proxmox hosts the virtualised side, including the file server and the home automation appliance.
|
||||
|
||||
## What it proves
|
||||
|
||||
That a machine can be rebuilt from a description, and that the same environment follows the person between machines instead of being re-created by memory.
|
||||
|
||||
## Limits stated on the page
|
||||
|
||||
The terminal-first setup is deliberate: a heavier desktop was downgraded to the terminal on one machine for memory headroom. A phone-as-server experiment is on hold, not shipped, and is described as on hold.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. Source facts: evidence notes section 3.
|
||||
31
content/platform/l3/platform-signage.md
Normal file
31
content/platform/l3/platform-signage.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: platform-signage
|
||||
area: platform
|
||||
level: 3
|
||||
title: "Artefact — Signage infrastructure · screens as a managed fleet"
|
||||
claim: "HDMI-CEC control of power · rotation · mirroring and multi-screen layout — so a display fleet is driven by the platform rather than by a remote control."
|
||||
confidence: delivered
|
||||
period: "2014–"
|
||||
tech: [HDMI-CEC, Raspberry Pi, Python, JavaScript, FFmpeg]
|
||||
metrics: [{label: "commercial deployments evidenced", value: "salon · financial services business"}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, signage, hdmi-cec, artefact]
|
||||
---
|
||||
|
||||
# Artefact — Signage infrastructure · screens as a managed fleet
|
||||
|
||||
**Status: stub.** The CEC command set and a layout diagram land in Phase 7.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
The platform side of the signage product: the codes and control path that switch screens on and off, rotate and mirror output, and lay out multi-screen displays, including synchronised playback across screens in one site.
|
||||
|
||||
## What it proves
|
||||
|
||||
Device-level control combined with fleet management. This is the same skill the edge pages show on small devices, applied to physical displays that other people depend on.
|
||||
|
||||
## Confidence
|
||||
|
||||
`delivered` — this ran in commercial deployments. The product's business status is stated separately on the Products pages, where the honest position is that the software is being rebuilt and three businesses still run it.
|
||||
31
content/platform/l3/platform-tuios-package.md
Normal file
31
content/platform/l3/platform-tuios-package.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
id: platform-tuios-package
|
||||
area: platform
|
||||
level: 3
|
||||
title: "Artefact — A hand-written Nix package with an exit plan"
|
||||
claim: "Twenty-five lines of Nix that pin a tool at 0.10.1 over nixpkgs' 0.7.0 — with a verified hash · a written reason and a written condition for deleting the file."
|
||||
confidence: running
|
||||
period: "2026–"
|
||||
tech: [Nix, NixOS]
|
||||
metrics: [{label: "pinned version", value: "0.10.1"}, {label: "nixpkgs version it overrides", value: "0.7.0"}]
|
||||
artefacts: []
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, nix, packaging, artefact]
|
||||
---
|
||||
|
||||
# Artefact — A hand-written Nix package with an exit plan
|
||||
|
||||
**Status: stub.** The whole file is short enough to publish verbatim; it lands in Phase 7.
|
||||
|
||||
## What the artefact is
|
||||
|
||||
A package definition for the agent operations console: `fetchurl` against a released artifact with a verified hash, a documented reason for overriding nixpkgs, an `installPhase` that stages the binary, and a comment stating the condition under which the file should be deleted.
|
||||
|
||||
## What it proves
|
||||
|
||||
More than knowing Nix exists. The signals are that someone noticed a version gap, fixed it locally instead of waiting, pinned it so the fleet is reproducible, and wrote down when to remove their own patch. Knowing when to delete your own override is the senior part.
|
||||
|
||||
## When it is delivered
|
||||
|
||||
Phase 7. The file is in the infrastructure repository; source fact: content spine section 4.2.
|
||||
66
content/platform/platform-estate.md
Normal file
66
content/platform/platform-estate.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: platform-estate
|
||||
area: platform
|
||||
level: 2
|
||||
title: "A small estate run to a documented standard"
|
||||
claim: "Fifty or more containers across four hosts on declarative configuration — with packaging discipline · encrypted backups and a restore runbook · loopback-bound services · and one public listener."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [NixOS, Proxmox, Docker, Caddy, Tailscale, Borg, Kopia, AWS S3, HDMI-CEC]
|
||||
metrics: [{label: "containers in the estate", value: 50}, {label: "hosts", value: 4}, {label: "backup tiers", value: "Borg · Kopia · AWS"}, {label: "public listeners", value: 1}]
|
||||
artefacts: [{type: doc, label: "Declarative multi-host configuration", url: "content/platform/l3/platform-nixos.md"}, {type: doc, label: "A hand-written Nix package with an exit plan", url: "content/platform/l3/platform-tuios-package.md"}, {type: doc, label: "Container inventory", url: "content/platform/l3/platform-containers.md"}, {type: doc, label: "Backups and restore runbook", url: "content/platform/l3/platform-backups.md"}, {type: doc, label: "Network layout and remote access", url: "content/platform/l3/platform-network.md"}, {type: doc, label: "Signage infrastructure — screens as a managed fleet", url: "content/platform/l3/platform-signage.md"}]
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, devops, nixos, docker, backups, networking]
|
||||
---
|
||||
|
||||
# A small estate run to a documented standard
|
||||
|
||||
**Capability statement.** Four hosts, fifty or more containers, configuration in version control instead of in a shell history, and one place where traffic enters. The estate is deliberately small because it is run rather than demonstrated.
|
||||
|
||||
## What is actually run
|
||||
|
||||
**Declarative configuration.** NixOS is the base on the machines that matter, with the desktop and the terminal replicated across them so an environment can be rebuilt from a description. Proxmox runs the virtualised side — Ubuntu file server and a Home Assistant appliance alongside the desktop hosts. The point of the arrangement is repeatability: a machine is a configuration, not a pet.
|
||||
|
||||
**Packaging.** When a tool is missing or stale in nixpkgs, it gets a derivation rather than a manual install. The TUIOS package pins 0.10.1 over nixpkgs' 0.7.0 with `fetchurl` and a verified hash, documents why the override exists, and states the condition for deleting it. A patch with an exit plan is maintenance; a patch without one is debt.
|
||||
|
||||
**Container estate.** Fifty or more containers run across the hosts — the file server and media services, the automation layer, the AI services, traffic for public ingress, and the tools used to build all of it. Each new service is given its own port, its own folder and a memory cap equal to its swap cap, so it cannot take the host's swap.
|
||||
|
||||
**Networking.** Remote access is a private mesh rather than an exposed SSH port: Tailscale across the machines, SSH on every host, and a phone used as a terminal. Services bind to loopback; Caddy is the only public listener, terminating TLS at the edge host and proxying the sites that are allowed to be seen.
|
||||
|
||||
**Storage and backups.** Three tiers, each covering a different failure: local snapshots on the machine, a copy on another machine over the network, and an offsite copy in object storage. Retention is stated in the job (daily, weekly, monthly, annual) and a restore runbook sits next to the jobs, because a backup nobody has restored from is an assumption.
|
||||
|
||||
**Observability and operations.** Resource use is watched at the host level, because the runtime host is memory-bound and a new service can destabilise the ones people rely on. The agent fleet is observed as a fleet through TUIOS — sessions, state and approvals in one console — rather than by tailing logs on four machines.
|
||||
|
||||
**Signage infrastructure.** The display work is treated as a fleet to be managed: HDMI-CEC control for power, rotation, mirroring and multi-screen layout, so screens are driven by the platform rather than by a person with a remote control.
|
||||
|
||||
## Evidence
|
||||
|
||||
| Claim | Evidence | Artefact |
|
||||
|---|---|---|
|
||||
| Configuration is declarative and replicated | NixOS hosts with shared configuration; Proxmox for the virtualised side | [Declarative configuration](l3/platform-nixos.md) |
|
||||
| Tooling is packaged rather than hand-installed | `pkgs/tuios.nix` pinning 0.10.1 with a documented removal condition | [Nix package](l3/platform-tuios-package.md) |
|
||||
| Fifty or more containers are operated | Inventory by host and by purpose | [Container inventory](l3/platform-containers.md) |
|
||||
| Backups are three-tier with a restore runbook | Borg on two hosts, Kopia and Backrest on the edge host, offsite object storage | [Backups](l3/platform-backups.md) |
|
||||
| One public listener | Loopback-bound services behind Caddy at the edge | [Network](l3/platform-network.md) |
|
||||
| Screens are managed as a fleet | HDMI-CEC control of power, rotation and layout | [Signage infrastructure](l3/platform-signage.md) |
|
||||
|
||||
## Trade-offs and limits
|
||||
|
||||
- **Memory over hardware.** The runtime host runs 15 GiB with little free and swap in use. The response was caps, fewer and smaller services, and moving heavy work to the gateway rather than buying another machine. Every new service is sized before it is deployed, and the ceiling for this site is one gigabyte and four containers.
|
||||
- **Self-hosting is a choice with a cost.** Monitoring, backups, ingress and the AI gateway are all operated here, which means the failure modes are also operated here. The mitigation is documentation and measurement, not optimism.
|
||||
- **Rejected on purpose.** A long list of tools was evaluated and refused — Airflow for RAM, self-hosted Langfuse for six containers it could not afford, LiteLLM because it would duplicate the existing gateway, and a pile of documentation platforms. "Alternatives considered" is kept because the reasoning is the senior artifact.
|
||||
- **Not everything is automated.** Some operations are still a documented command run by a person. The runbook exists precisely because the automations do not cover everything.
|
||||
|
||||
## Drill-downs
|
||||
|
||||
- [Declarative multi-host configuration](l3/platform-nixos.md) — level 3
|
||||
- [A hand-written Nix package with an exit plan](l3/platform-tuios-package.md) — level 3
|
||||
- [Container inventory](l3/platform-containers.md) — level 3
|
||||
- [Backups and restore runbook](l3/platform-backups.md) — level 3
|
||||
- [Network layout and remote access](l3/platform-network.md) — level 3
|
||||
- [Signage infrastructure — screens as a managed fleet](l3/platform-signage.md) — level 3
|
||||
|
||||
## Period and confidence
|
||||
|
||||
`period: 2020–`, anchored on the homelab year in the evidence notes. Confidence is `running`: this is the current estate, verified 2026-10-26.
|
||||
25
content/platform/platform-overview.md
Normal file
25
content/platform/platform-overview.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
id: platform-overview
|
||||
area: platform
|
||||
level: 1
|
||||
title: "Platform & Infrastructure"
|
||||
claim: "Runs a multi-machine NixOS and Proxmox estate — fifty-plus containers · declarative configuration · encrypted backups with a written restore runbook · and public ingress — sized to the hardware rather than the budget."
|
||||
confidence: running
|
||||
period: "2020–"
|
||||
tech: [NixOS, Proxmox, Docker, Caddy, Tailscale, Borg, Kopia, AWS S3]
|
||||
metrics: [{label: "containers in the estate", value: 50}, {label: "hosts", value: 4}, {label: "backup tiers", value: "Borg · Kopia · AWS"}]
|
||||
artefacts: [{type: doc, label: "Declarative multi-host configuration", url: "content/platform/l3/platform-nixos.md"}, {type: doc, label: "Backups and restore runbook", url: "content/platform/l3/platform-backups.md"}, {type: doc, label: "A hand-written Nix package with an exit plan", url: "content/platform/l3/platform-tuios-package.md"}]
|
||||
public: true
|
||||
last_verified: 2026-10-26
|
||||
tags: [platform, devops, nixos, docker, backups]
|
||||
---
|
||||
|
||||
# Platform & Infrastructure
|
||||
|
||||
**Claim.** Fifty or more containers across four hosts, configuration declared rather than hand-applied, encrypted backups on three machines with a restore runbook beside them, and one public listener at the edge.
|
||||
|
||||
**Status.** Running. Figures trace to the approved metric set and the infrastructure reference; verified 2026-10-26.
|
||||
|
||||
**The constraint that shaped it.** The runtime host is memory-bound rather than CPU-bound. Every service in this estate carries a memory cap and is bound to loopback, which is why the platform reads as engineering under constraint instead of hardware shopping.
|
||||
|
||||
**Start here.** [The capability page](platform-estate.md) covers what runs, where, and what was rejected.
|
||||
Reference in New Issue
Block a user