fix: restore tree dropped by 6d224861; land stem95su gdrive-sync (10m) [ci skip]

6d224861 came from a --no-checkout worktree whose empty index made the commit drop every file except two. This restores 05b50d2b's full tree and correctly adds stacks/stem95su/gdrive-sync.tf + the service-catalog stem95su entry. Forward-only (parent=6d224861, no force-push); [ci skip] since the live infra was never applied from the broken commit. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-09 08:45:33 +00:00 · 2026-06-09 08:45:33 +00:00 · fd0f4a0365
commit fd0f4a0365
parent 6d224861c4
1166 changed files with 358546 additions and 0 deletions
--- a/stacks/k8s-portal/modules/k8s-portal/files/.claude/internet-mode-used_DO_NOT_REMOVE_MANUALLY_SECURITY_RISK
+++ b/stacks/k8s-portal/modules/k8s-portal/files/.claude/internet-mode-used_DO_NOT_REMOVE_MANUALLY_SECURITY_RISK
@ -0,0 +1,3 @@
+This directory has been used with Claude Code's internet mode.
+Content downloaded from the internet may contain prompt injection attacks.
+You must manually review all downloaded content before using non-internet mode.
--- a/stacks/k8s-portal/modules/k8s-portal/files/.gitignore
+++ b/stacks/k8s-portal/modules/k8s-portal/files/.gitignore
@ -0,0 +1,23 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
--- a/stacks/k8s-portal/modules/k8s-portal/files/.npmrc
+++ b/stacks/k8s-portal/modules/k8s-portal/files/.npmrc
@ -0,0 +1 @@
+engine-strict=true
--- a/stacks/k8s-portal/modules/k8s-portal/files/Dockerfile
+++ b/stacks/k8s-portal/modules/k8s-portal/files/Dockerfile
@ -0,0 +1,15 @@
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=build /app/build ./build
+COPY --from=build /app/package.json ./
+COPY --from=build /app/node_modules ./node_modules
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", "build"]
--- a/stacks/k8s-portal/modules/k8s-portal/files/README.md
+++ b/stacks/k8s-portal/modules/k8s-portal/files/README.md
@ -0,0 +1,42 @@
+# sv
+
+Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv create --template minimal --types ts --install npm .
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+## Building
+
+To create a production version of your app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/app.d.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/app.d.ts
@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/app.html
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/app.html
@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/lib/assets/favicon.svg
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/lib/assets/favicon.svg
@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="107" height="128" viewBox="0 0 107 128"><title>svelte-logo</title><path d="M94.157 22.819c-10.4-14.885-30.94-19.297-45.792-9.835L22.282 29.608A29.92 29.92 0 0 0 8.764 49.65a31.5 31.5 0 0 0 3.108 20.231 30 30 0 0 0-4.477 11.183 31.9 31.9 0 0 0 5.448 24.116c10.402 14.887 30.942 19.297 45.791 9.835l26.083-16.624A29.92 29.92 0 0 0 98.235 78.35a31.53 31.53 0 0 0-3.105-20.232 30 30 0 0 0 4.474-11.182 31.88 31.88 0 0 0-5.447-24.116" style="fill:#ff3e00"/><path d="M45.817 106.582a20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.503 18 18 0 0 1 .624-2.435l.49-1.498 1.337.981a33.6 33.6 0 0 0 10.203 5.098l.97.294-.09.968a5.85 5.85 0 0 0 1.052 3.878 6.24 6.24 0 0 0 6.695 2.485 5.8 5.8 0 0 0 1.603-.704L69.27 76.28a5.43 5.43 0 0 0 2.45-3.631 5.8 5.8 0 0 0-.987-4.371 6.24 6.24 0 0 0-6.698-2.487 5.7 5.7 0 0 0-1.6.704l-9.953 6.345a19 19 0 0 1-5.296 2.326 20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.502 17.99 17.99 0 0 1 8.13-12.052l26.081-16.623a19 19 0 0 1 5.3-2.329 20.72 20.72 0 0 1 22.237 8.243 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-.624 2.435l-.49 1.498-1.337-.98a33.6 33.6 0 0 0-10.203-5.1l-.97-.294.09-.968a5.86 5.86 0 0 0-1.052-3.878 6.24 6.24 0 0 0-6.696-2.485 5.8 5.8 0 0 0-1.602.704L37.73 51.72a5.42 5.42 0 0 0-2.449 3.63 5.79 5.79 0 0 0 .986 4.372 6.24 6.24 0 0 0 6.698 2.486 5.8 5.8 0 0 0 1.602-.704l9.952-6.342a19 19 0 0 1 5.295-2.328 20.72 20.72 0 0 1 22.237 8.242 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-8.13 12.053l-26.081 16.622a19 19 0 0 1-5.3 2.328" style="fill:#fff"/></svg>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/lib/index.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/lib/index.ts
@ -0,0 +1 @@
+// place files you want to import through the `$lib` alias in this folder.
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/+layout.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/+layout.svelte
@ -0,0 +1,64 @@
+<script lang="ts">
+	import favicon from '$lib/assets/favicon.svg';
+	import { page } from '$app/stores';
+
+	let { children } = $props();
+</script>
+
+<svelte:head>
+	<link rel="icon" href={favicon} />
+</svelte:head>
+
+<nav>
+	<div class="nav-inner">
+		<a href="/" class="brand">K8s Portal</a>
+		<div class="links">
+			<a href="/onboarding" class:active={$page.url.pathname === '/onboarding'}>Getting Started</a>
+			<a href="/architecture" class:active={$page.url.pathname === '/architecture'}>Architecture</a>
+			<a href="/services" class:active={$page.url.pathname === '/services'}>Services</a>
+			<a href="/contributing" class:active={$page.url.pathname === '/contributing'}>Contributing</a>
+			<a href="/troubleshooting" class:active={$page.url.pathname === '/troubleshooting'}>Help</a>
+		</div>
+	</div>
+</nav>
+
+{@render children()}
+
+<style>
+	nav {
+		background: #1a1a2e;
+		padding: 0.75rem 1rem;
+		position: sticky;
+		top: 0;
+		z-index: 100;
+	}
+	.nav-inner {
+		max-width: 768px;
+		margin: 0 auto;
+		display: flex;
+		align-items: center;
+		gap: 1.5rem;
+		flex-wrap: wrap;
+	}
+	.brand {
+		color: #e0e0e0;
+		text-decoration: none;
+		font-weight: 700;
+		font-size: 1.1rem;
+	}
+	.links {
+		display: flex;
+		gap: 1rem;
+		flex-wrap: wrap;
+	}
+	.links a {
+		color: #a0a0c0;
+		text-decoration: none;
+		font-size: 0.9rem;
+		padding: 0.25rem 0;
+	}
+	.links a:hover, .links a.active {
+		color: #ffffff;
+		border-bottom: 2px solid #4fc3f7;
+	}
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/+page.server.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/+page.server.ts
@ -0,0 +1,33 @@
+import type { PageServerLoad } from './$types';
+import { readFileSync } from 'fs';
+
+interface UserRole {
+	role: string;
+	namespaces: string[];
+}
+
+export const load: PageServerLoad = async ({ request }) => {
+	const email = request.headers.get('x-authentik-email') || 'unknown';
+	const username = request.headers.get('x-authentik-username') || 'unknown';
+	const groups = request.headers.get('x-authentik-groups') || '';
+
+	// Read user roles from ConfigMap-mounted file
+	let userRole: UserRole = { role: 'unknown', namespaces: [] };
+	try {
+		const usersJson = readFileSync('/config/users.json', 'utf-8');
+		const users = JSON.parse(usersJson);
+		if (users[email]) {
+			userRole = users[email];
+		}
+	} catch {
+		// ConfigMap not mounted or parse error
+	}
+
+	return {
+		email,
+		username,
+		groups: groups.split('|').filter(Boolean),
+		role: userRole.role,
+		namespaces: userRole.namespaces
+	};
+};
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/+page.svelte
@ -0,0 +1,102 @@
+<script lang="ts">
+	let { data } = $props();
+</script>
+
+<main>
+	<h1>Kubernetes Access Portal</h1>
+
+	<div class="callout warning">
+		<strong>VPN Required</strong> — The cluster is on a private network. You need Headscale VPN access before kubectl will work.
+		<a href="/onboarding">See the Getting Started guide</a> for VPN setup instructions.
+	</div>
+
+	<section>
+		<h2>Your Identity</h2>
+		<p><strong>Username:</strong> {data.username}</p>
+		<p><strong>Email:</strong> {data.email}</p>
+		<p><strong>Role:</strong> {data.role}</p>
+		{#if data.namespaces.length > 0}
+			<p><strong>Namespaces:</strong> {data.namespaces.join(', ')}</p>
+		{/if}
+	</section>
+
+	{#if data.role === 'namespace-owner'}
+		<section>
+			<h2>Your Namespace</h2>
+			<p><strong>Assigned namespaces:</strong> {data.namespaces.join(', ')}</p>
+
+			<h3>Quick Commands</h3>
+			<pre>
+# Check your pods
+kubectl get pods -n {data.namespaces[0]}
+
+# View quota usage
+kubectl describe resourcequota -n {data.namespaces[0]}
+
+# Log into Vault
+vault login -method=oidc
+
+# Store a secret
+vault kv put secret/{data.username}/myapp KEY=value
+
+# Get K8s deploy token
+vault write kubernetes/creds/{data.namespaces[0]}-deployer \
+  kubernetes_namespace={data.namespaces[0]}</pre>
+		</section>
+	{/if}
+
+	<section>
+		<h2>Get Started</h2>
+		<ol>
+			{#if data.role === 'namespace-owner'}
+				<li><a href="/onboarding?role=namespace-owner">Complete the namespace-owner onboarding guide</a></li>
+			{:else}
+				<li><a href="/onboarding">Complete the onboarding guide</a> (VPN, kubectl, git)</li>
+			{/if}
+			<li><a href="/setup">Install kubectl and kubelogin</a></li>
+			<li><a href="/download">Download your kubeconfig</a></li>
+			<li>Run <code>kubectl get namespaces</code> to verify access</li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>Resources</h2>
+		<ul>
+			<li><a href="/architecture">Architecture overview</a></li>
+			<li><a href="/services">Service catalog</a></li>
+			<li><a href="/contributing">How to contribute</a></li>
+			<li><a href="/troubleshooting">Troubleshooting</a></li>
+		</ul>
+	</section>
+</main>
+
+<style>
+	main {
+		max-width: 768px;
+		margin: 2rem auto;
+		padding: 0 1rem;
+		font-family: system-ui, -apple-system, sans-serif;
+		line-height: 1.6;
+	}
+	code {
+		background: #f0f0f0;
+		padding: 2px 6px;
+		border-radius: 3px;
+	}
+	section {
+		margin: 2rem 0;
+	}
+	.callout {
+		padding: 1rem;
+		border-radius: 6px;
+		margin: 1rem 0;
+	}
+	.callout.warning {
+		background: #fff3cd;
+		border-left: 4px solid #ffc107;
+	}
+	.callout a {
+		color: #856404;
+		font-weight: 600;
+	}
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/agent/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/agent/+page.svelte
@ -0,0 +1,61 @@
+<main class="content">
+	<h1>Agent Bootstrap</h1>
+	<p>Point any AI coding agent at this cluster and it can bootstrap itself automatically.</p>
+
+	<section>
+		<h2>For AI Agents</h2>
+		<p>Fetch the machine-readable bootstrap document:</p>
+		<pre>curl -fsSL https://k8s-portal.viktorbarzin.me/agent</pre>
+		<p>This returns a plain-text markdown document with everything an agent needs: setup commands, critical rules, secrets workflow, Terraform conventions, key file paths, and common operations.</p>
+	</section>
+
+	<section>
+		<h2>Usage with Claude Code</h2>
+		<pre>claude "$(curl -fsSL https://k8s-portal.viktorbarzin.me/agent)" "Deploy a new echo service"</pre>
+		<p>Or within a session:</p>
+		<ol>
+			<li>Clone the repo: <code>git clone https://github.com/ViktorBarzin/infra.git && cd infra</code></li>
+			<li>Start Claude Code: <code>claude</code></li>
+			<li>Claude auto-reads <code>AGENTS.md</code> and <code>.claude/CLAUDE.md</code> from the repo</li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>Usage with Codex / Other Agents</h2>
+		<ol>
+			<li>Clone the repo and <code>cd</code> into it</li>
+			<li>Run the setup script: <code>bash &lt;(curl -fsSL https://k8s-portal.viktorbarzin.me/setup/script?os=linux)</code></li>
+			<li>Start the agent — it will read <code>AGENTS.md</code> for instructions</li>
+		</ol>
+		<p>If the agent doesn't auto-read <code>AGENTS.md</code>, feed it the bootstrap doc:</p>
+		<pre>curl -fsSL https://k8s-portal.viktorbarzin.me/agent</pre>
+	</section>
+
+	<section>
+		<h2>What the Agent Gets</h2>
+		<ul>
+			<li>Quick-start commands (setup script, repo clone)</li>
+			<li>Critical rules (no kubectl apply, no plaintext secrets, no NFS restart)</li>
+			<li>Sealed Secrets workflow (kubeseal self-service)</li>
+			<li>Terraform conventions (fileset pattern, tiers, storage, shared vars)</li>
+			<li>Key file paths in the repo</li>
+			<li>Common operations (deploy, fix pods, add secrets)</li>
+			<li>Contributing workflow (branch, PR, review, CI)</li>
+		</ul>
+	</section>
+
+	<section>
+		<h2>The <code>/agent</code> Endpoint</h2>
+		<p>The endpoint is <strong>unauthenticated</strong> — no login required. Agents can <code>curl</code> or <code>WebFetch</code> it directly without a browser session, just like the setup script.</p>
+		<p>Content-Type: <code>text/plain</code> — no HTML parsing needed.</p>
+	</section>
+</main>
+
+<style>
+	.content { max-width: 768px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
+	.content h1 { border-bottom: 1px solid #e0e0e0; padding-bottom: 0.5rem; }
+	.content h2 { margin-top: 2rem; color: #333; }
+	.content pre { background: #1e1e1e; color: #d4d4d4; padding: 1rem; border-radius: 6px; overflow-x: auto; }
+	.content code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; }
+	section { margin: 2rem 0; }
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/agent/+server.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/agent/+server.ts
@ -0,0 +1,161 @@
+import type { RequestHandler } from './$types';
+
+const BOOTSTRAP_DOC = `# Infrastructure Cluster — AI Agent Bootstrap
+
+> Fetch this document: \`curl -fsSL https://k8s-portal.viktorbarzin.me/agent\`
+
+## Quick Start
+
+\`\`\`bash
+# 1. Install tools (kubectl, kubelogin, kubeseal)
+bash <(curl -fsSL https://k8s-portal.viktorbarzin.me/setup/script?os=linux)
+
+# 2. Clone the infrastructure repo
+git clone https://github.com/ViktorBarzin/infra.git && cd infra
+
+# 3. Verify cluster access (opens browser for OIDC login on first run)
+kubectl get namespaces
+\`\`\`
+
+## Critical Rules (MUST FOLLOW)
+
+- **ALL changes through Terraform/Terragrunt** — NEVER \`kubectl apply/edit/patch/delete\` for persistent changes. Read-only kubectl is fine.
+- **NEVER put secrets in plaintext** — use Sealed Secrets (\`kubeseal\`) or \`secrets.sops.json\` (SOPS-encrypted).
+- **NEVER restart NFS on TrueNAS** — causes cluster-wide mount failures across all pods.
+- **NEVER commit secrets** — triple-check before every commit.
+- **\`[ci skip]\` in commit messages** when changes were already applied locally.
+- **Ask before \`git push\`** — always confirm with the user first.
+
+## Sealed Secrets (Self-Service)
+
+You can manage your own secrets without SOPS access using \`kubeseal\`:
+
+\`\`\`bash
+# 1. Create a sealed secret
+kubectl create secret generic <name> \\
+  --from-literal=key=value -n <namespace> \\
+  --dry-run=client -o yaml | \\
+  kubeseal --controller-name sealed-secrets \\
+    --controller-namespace sealed-secrets -o yaml > sealed-<name>.yaml
+
+# 2. Place the file in the stack directory: stacks/<service>/sealed-<name>.yaml
+
+# 3. Ensure the stack's main.tf has the fileset block (add if missing):
+\`\`\`
+
+\`\`\`hcl
+resource "kubernetes_manifest" "sealed_secrets" {
+  for_each = fileset(path.module, "sealed-*.yaml")
+  manifest = yamldecode(file("\${path.module}/\${each.value}"))
+}
+\`\`\`
+
+\`\`\`bash
+# 4. Push to PR — CI runs terragrunt apply — controller decrypts into real K8s Secrets
+\`\`\`
+
+- Files MUST match the \`sealed-*.yaml\` glob pattern.
+- Only the in-cluster controller has the private key. \`kubeseal\` uses the public key — safe to distribute.
+- The \`kubernetes_manifest\` block is safe to add even with zero sealed-*.yaml files (empty for_each).
+
+## SOPS Secrets (Admin-Only Fallback)
+
+For secrets requiring admin access (shared infra passwords, API keys):
+- **\`secrets.sops.json\`** — SOPS-encrypted secrets (JSON format)
+- **Edit**: \`sops secrets.sops.json\` (opens $EDITOR, re-encrypts on save)
+- **Add**: \`sops set secrets.sops.json '["new_key"]' '"value"'\`
+- **Operators without SOPS keys**: comment on your PR asking Viktor to add the secret.
+
+## Terraform Conventions
+
+### Execution
+- **Apply a service**: \`scripts/tg apply --non-interactive\` (auto-decrypts SOPS secrets)
+- **Plan**: \`scripts/tg plan --non-interactive\`
+- **kubectl**: \`kubectl --kubeconfig $(pwd)/config\`
+- **Health check**: \`bash scripts/cluster_healthcheck.sh --quiet\`
+
+### Key Paths
+| Path | Purpose |
+|------|---------|
+| \`stacks/<service>/main.tf\` | Service definition |
+| \`stacks/platform/modules/<module>/\` | Core infra modules (~22) |
+| \`modules/kubernetes/ingress_factory/\` | Standardized ingress (auth, rate limiting, anti-AI) |
+| \`modules/kubernetes/nfs_volume/\` | NFS volume module (CSI-backed, soft mount) |
+| \`config.tfvars\` | Non-secret configuration (plaintext) |
+| \`secrets.sops.json\` | All secrets (SOPS-encrypted JSON) |
+| \`scripts/cluster_healthcheck.sh\` | 42-check cluster health script |
+| \`AGENTS.md\` | Full AI agent instructions (auto-loaded by most agents) |
+
+### Tier System
+\`0-core\` | \`1-cluster\` | \`2-gpu\` | \`3-edge\` | \`4-aux\`
+
+Kyverno auto-generates LimitRange + ResourceQuota per namespace based on tier label.
+- Containers without explicit \`resources {}\` get default limits (256Mi for edge/aux — causes OOMKill for heavy apps)
+- Always set explicit resources on containers that need more than defaults
+- Opt-out labels: \`resource-governance/custom-quota=true\` / \`resource-governance/custom-limitrange=true\`
+
+### Storage
+- **NFS** (\`nfs-truenas\` StorageClass): For app data. Use the \`nfs_volume\` module.
+- **iSCSI** (\`iscsi-truenas\` StorageClass): For databases (PostgreSQL, MySQL).
+
+### Shared Variables (never hardcode)
+\`var.nfs_server\`, \`var.redis_host\`, \`var.postgresql_host\`, \`var.mysql_host\`, \`var.ollama_host\`, \`var.mail_host\`
+
+## Architecture
+
+- Terragrunt-based homelab managing a Kubernetes cluster (5 nodes, v1.34.2) on Proxmox VMs
+- 70+ services, each in \`stacks/<service>/\` with its own Terraform state
+- Core platform: \`stacks/platform/modules/\` (Traefik, Kyverno, monitoring, dbaas, sealed-secrets, etc.)
+- Public domain: \`viktorbarzin.me\` (Cloudflare) | Internal: \`viktorbarzin.lan\` (Technitium DNS)
+- CI/CD: Woodpecker CI — PRs run plan, merges to master auto-apply platform stack
+
+## Common Operations
+
+### Deploy a New Service
+1. Copy an existing stack as template: \`cp -r stacks/echo stacks/my-service\`
+2. Edit \`main.tf\` — update image, ports, ingress, resources
+3. Add DNS in \`config.tfvars\`
+4. Apply platform first if needed, then the service
+
+### Fix Crashed Pods
+1. Run \`bash scripts/cluster_healthcheck.sh --quiet\`
+2. Safe to delete evicted/failed pods and CrashLoopBackOff pods with >10 restarts
+3. OOMKilled? Check \`kubectl describe limitrange tier-defaults -n <ns>\` and increase \`resources.limits.memory\`
+
+### Add a Secret
+- **Self-service**: Use \`kubeseal\` (see Sealed Secrets section above)
+- **Admin**: \`sops set secrets.sops.json '["key"]' '"value"'\` then commit
+
+## Contributing Workflow
+
+1. Create a branch: \`git checkout -b fix/my-change\`
+2. Make changes in \`stacks/<service>/main.tf\`
+3. Push and open a PR: \`git push -u origin fix/my-change\`
+4. Viktor reviews and merges
+5. CI applies automatically — Slack notification when done
+
+## Infrastructure Details
+
+- **Proxmox**: 192.168.1.127 (Dell R730, 22c/44t, 142GB RAM)
+- **Nodes**: k8s-master (10.0.20.100), node1 (GPU, Tesla T4), node2-4
+- **GPU workloads**: \`node_selector = { "nvidia.com/gpu.present" : "true" }\` + toleration \`nvidia.com/gpu\` (label auto-applied by gpu-feature-discovery, no hostname pins)
+- **Pull-through cache**: 10.0.20.10 — use versioned image tags (cache serves stale :latest manifests)
+- **MySQL InnoDB Cluster**: 3 instances on iSCSI
+- **SMTP**: \`var.mail_host\` port 587 STARTTLS
+
+## Further Reading
+
+- Full agent instructions: \`AGENTS.md\` in the repo root
+- Patterns and examples: \`.claude/reference/patterns.md\`
+- Service catalog: \`.claude/reference/service-catalog.md\`
+- Onboarding guide: https://k8s-portal.viktorbarzin.me/onboarding
+`;
+
+export const GET: RequestHandler = async () => {
+	return new Response(BOOTSTRAP_DOC, {
+		headers: {
+			'Content-Type': 'text/plain; charset=utf-8',
+			'Cache-Control': 'public, max-age=3600'
+		}
+	});
+};
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/architecture/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/architecture/+page.svelte
@ -0,0 +1,143 @@
+<main class="content">
+	<h1>Architecture</h1>
+
+	<section>
+		<h2>Overview</h2>
+		<p>The infrastructure runs on a single Dell R730 server (22 CPU cores, 142GB RAM) using Proxmox to manage virtual machines. Five of those VMs form a Kubernetes cluster that runs 70+ services.</p>
+		<pre class="output">
+Proxmox (Dell R730)
+ ├── k8s-master  (10.0.20.100) — control plane
+ ├── k8s-node1   (10.0.20.101) — GPU node (Tesla T4)
+ ├── k8s-node2   (10.0.20.102) — worker
+ ├── k8s-node3   (10.0.20.103) — worker
+ ├── k8s-node4   (10.0.20.104) — worker
+ ├── TrueNAS     (10.0.10.15)  — storage (NFS + iSCSI)
+ └── pfSense     (10.0.20.1)   — firewall + gateway</pre>
+	</section>
+
+	<section>
+		<h2>Networking</h2>
+		<ul>
+			<li><strong>Public domain</strong>: <code>viktorbarzin.me</code> — managed by Cloudflare</li>
+			<li><strong>Internal domain</strong>: <code>viktorbarzin.lan</code> — managed by Technitium DNS</li>
+			<li><strong>Ingress</strong>: Cloudflare → Traefik → services</li>
+			<li><strong>VPN</strong>: Headscale (self-hosted Tailscale)</li>
+		</ul>
+	</section>
+
+	<section>
+		<h2>Storage</h2>
+		<ul>
+			<li><strong>NFS</strong> (<code>nfs-truenas</code>) — for app data (files, configs, media). Stored on TrueNAS.</li>
+			<li><strong>iSCSI</strong> (<code>iscsi-truenas</code>) — for databases (PostgreSQL, MySQL). Block storage.</li>
+		</ul>
+	</section>
+
+	<section>
+		<h2>Service Tiers</h2>
+		<p>Services are organized into tiers that control resource limits and restart priority:</p>
+		<table>
+			<thead><tr><th>Tier</th><th>Examples</th><th>Priority</th></tr></thead>
+			<tbody>
+			<tr><td><strong>0-core</strong></td><td>Traefik, DNS, VPN, Auth</td><td>Highest — never evicted</td></tr>
+			<tr><td><strong>1-cluster</strong></td><td>Redis, Prometheus, CrowdSec</td><td>High</td></tr>
+			<tr><td><strong>2-gpu</strong></td><td>Ollama, Immich ML, Whisper</td><td>Medium</td></tr>
+			<tr><td><strong>3-edge</strong></td><td>Nextcloud, Paperless, Grafana</td><td>Normal</td></tr>
+			<tr><td><strong>4-aux</strong></td><td>Dashy, PrivateBin, CyberChef</td><td>Low — evicted first under pressure</td></tr>
+			</tbody>
+		</table>
+	</section>
+
+	<section>
+		<h2>Infrastructure as Code</h2>
+		<p>Everything is managed with <strong>Terraform</strong> (via <strong>Terragrunt</strong>). Each service has its own stack:</p>
+		<pre class="output">stacks/
+ ├── platform/       ← core infra (22 modules)
+ ├── url/            ← URL shortener (Shlink)
+ ├── immich/         ← photo library
+ ├── nextcloud/      ← file storage
+ └── ... (70+ more)</pre>
+		<p>Changes go through git: branch → PR → review → merge → CI applies automatically.</p>
+	</section>
+
+	<section>
+		<h2>Secrets &amp; State Encryption</h2>
+		<p>Terraform state is committed to git as SOPS-encrypted JSON. Secrets live in HashiCorp Vault.</p>
+		<pre class="output">
+Authentication &amp; Authorization
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+User → Authentik SSO (OIDC) → Vault Token
+                                  │
+                   ┌──────────────┼──────────────┐
+                   ▼              ▼              ▼
+            KV Secrets    Transit Keys    K8s Creds
+            (per-stack)   (per-stack)    (deployer)
+
+State Encryption Flow
+━━━━━━━━━━━━━━━━━━━━
+.tfstate ──SOPS──▶ .tfstate.enc ──git──▶ repo
+                      │
+              encrypted with:
+              ├── Vault Transit key (per-stack)
+              └── age keys (admin DR fallback)
+
+Access Control
+━━━━━━━━━━━━━━
+Admin:    vault-admin policy  → all transit keys
+User:     sops-user-* policy  → own stack keys only
+Fallback: age key on disk     → admin only (no users)</pre>
+	</section>
+
+	<section>
+		<h2>Request Flow</h2>
+		<pre class="output">
+Internet → Cloudflare (CDN + WAF)
+              │
+              ▼
+         Cloudflared tunnel
+              │
+              ▼
+         Traefik (3 replicas)
+         ├── CrowdSec bouncer (rate limit, bot block)
+         ├── Authentik forward-auth (SSO for protected apps)
+         └── TLS termination
+              │
+              ▼
+         K8s Service → Pod(s)
+              │
+              ├── NFS volume (app data)
+              └── iSCSI volume (databases)</pre>
+	</section>
+
+	<section>
+		<h2>CI/CD Pipeline</h2>
+		<pre class="output">
+git push
+   │
+   ├──▶ GitHub Actions (build Docker image, push to DockerHub)
+   │         │
+   │         ▼
+   │    POST Woodpecker API (trigger deploy)
+   │         │
+   │         ▼
+   │    Woodpecker (kubectl set image, Slack notify)
+   │
+   └──▶ Woodpecker (terragrunt apply — infra changes)
+              │
+              ▼
+         Kubernetes API → rolling update</pre>
+	</section>
+</main>
+
+<style>
+	.content { max-width: 768px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
+	.content h1 { border-bottom: 1px solid #e0e0e0; padding-bottom: 0.5rem; }
+	.content h2 { margin-top: 2rem; color: #333; }
+	.content pre { background: #1e1e1e; color: #d4d4d4; padding: 1rem; border-radius: 6px; overflow-x: auto; }
+	.content pre.output { background: #f5f5f5; color: #333; }
+	.content code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; }
+	section { margin: 2rem 0; }
+	table { border-collapse: collapse; width: 100%; }
+	th, td { border: 1px solid #ddd; padding: 0.5rem; text-align: left; }
+	th { background: #f5f5f5; }
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/contributing/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/contributing/+page.svelte
@ -0,0 +1,115 @@
+<main class="content">
+	<h1>How to Contribute</h1>
+
+	<section>
+		<h2>Workflow</h2>
+		<ol>
+			<li><strong>Create a branch</strong>: <code>git checkout -b fix/my-change</code></li>
+			<li><strong>Make your changes</strong> in <code>stacks/&lt;service&gt;/main.tf</code></li>
+			<li><strong>Push and open a PR</strong>: <code>git push -u origin fix/my-change</code></li>
+			<li><strong>Viktor reviews</strong> and merges</li>
+			<li><strong>CI applies</strong> automatically — Slack notification when done</li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>What you CAN change</h2>
+		<ul>
+			<li>Service configurations (image tags, environment variables, resource limits)</li>
+			<li>New services (add a new stack under <code>stacks/</code>)</li>
+			<li>Ingress routes, health probes, replica counts</li>
+		</ul>
+	</section>
+
+	<section>
+		<h2>What needs Viktor's review</h2>
+		<ul>
+			<li>CI pipeline changes (<code>.woodpecker/</code>)</li>
+			<li>Terragrunt configuration (<code>terragrunt.hcl</code>)</li>
+			<li>Secrets configuration (<code>.sops.yaml</code>)</li>
+			<li>Core platform modules (<code>stacks/platform/</code>)</li>
+		</ul>
+	</section>
+
+	<section>
+		<h2 class="danger-header">NEVER do these</h2>
+		<div class="callout danger">
+			<ul>
+				<li><strong>Never <code>kubectl apply/edit/patch</code></strong> — all changes go through Terraform</li>
+				<li><strong>Never put secrets in code</strong> — ask Viktor to add them to the encrypted secrets file</li>
+				<li><strong>Never restart NFS on TrueNAS</strong> — causes cluster-wide mount failures</li>
+				<li><strong>Never push directly to master</strong> — always use a PR</li>
+			</ul>
+		</div>
+	</section>
+
+	<section>
+		<h2>Need a new secret?</h2>
+		<p>Comment on your PR: "I need a database password for my-service." Viktor will add it to the encrypted secrets file and push to your branch.</p>
+		<p>Then reference it in your Terraform: <code>var.my_service_db_password</code></p>
+	</section>
+
+	<section>
+		<h2>Namespace Owner Workflow</h2>
+		<p>If you are a namespace owner, you can deploy your own apps:</p>
+		<ol>
+			<li>Clone the infra repo: <code>git clone https://github.com/ViktorBarzin/infra.git</code></li>
+			<li>Copy the template: <code>cp -r stacks/_template stacks/your-app</code></li>
+			<li>Rename: <code>mv stacks/your-app/main.tf.example stacks/your-app/main.tf</code></li>
+			<li>Edit <code>main.tf</code> — replace all <code>&lt;placeholders&gt;</code></li>
+			<li>Store secrets in Vault: <code>vault kv put secret/your-username/your-app KEY=value</code></li>
+			<li>Add your app domain to your <code>domains</code> list in Vault KV</li>
+			<li>Submit a PR, get it reviewed</li>
+			<li>After merge, admin runs <code>terragrunt apply</code></li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>CI Pipeline Template</h2>
+		<p>Create a <code>.woodpecker.yml</code> in your app's Forgejo repo:</p>
+		<pre>{`steps:
+  - name: build
+    image: woodpeckerci/plugin-docker-buildx
+    settings:
+      repo: your-dockerhub-user/myapp
+      tag: ["\${CI_PIPELINE_NUMBER}", "latest"]
+      username:
+        from_secret: dockerhub-username
+      password:
+        from_secret: dockerhub-token
+      platforms: linux/amd64
+
+  - name: deploy
+    image: hashicorp/vault:1.18.1
+    commands:
+      - export VAULT_ADDR=http://vault-active.vault.svc.cluster.local:8200
+      - export VAULT_TOKEN=$(vault write -field=token auth/kubernetes/login
+          role=ci jwt=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token))
+      - KUBE_TOKEN=$(vault write -field=service_account_token
+          kubernetes/creds/YOUR_NAMESPACE-deployer
+          kubernetes_namespace=YOUR_NAMESPACE)
+      - kubectl --server=https://kubernetes.default.svc
+          --token=$KUBE_TOKEN
+          --certificate-authority=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+          -n YOUR_NAMESPACE set image deployment/myapp
+          myapp=your-dockerhub-user/myapp:\${CI_PIPELINE_NUMBER}`}</pre>
+	</section>
+
+	<section>
+		<h2>Need a secret for your app?</h2>
+		<p>As a namespace owner, you manage your own secrets in Vault:</p>
+		<pre>vault kv put secret/your-username/your-app DB_PASSWORD=mysecret API_KEY=abc123</pre>
+		<p>Then reference them in your Terraform using a <code>data "vault_kv_secret_v2"</code> block.</p>
+	</section>
+</main>
+
+<style>
+	.content { max-width: 768px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
+	.content h1 { border-bottom: 1px solid #e0e0e0; padding-bottom: 0.5rem; }
+	.content h2 { margin-top: 2rem; color: #333; }
+	.content code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; }
+	section { margin: 2rem 0; }
+	.callout { padding: 1rem; border-radius: 6px; margin: 1rem 0; }
+	.callout.danger { background: #f8d7da; border-left: 4px solid #dc3545; }
+	.danger-header { color: #dc3545; }
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/download/+server.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/download/+server.ts
@ -0,0 +1,58 @@
+import type { RequestHandler } from './$types';
+import { readFileSync } from 'fs';
+
+const CLUSTER_SERVER = 'https://10.0.20.100:6443';
+const OIDC_ISSUER = 'https://authentik.viktorbarzin.me/application/o/kubernetes/';
+const OIDC_CLIENT_ID = 'kubernetes';
+
+export const GET: RequestHandler = async ({ request }) => {
+	const email = request.headers.get('x-authentik-email') || 'user';
+
+	// Read CA cert from mounted ConfigMap
+	let caCert = '';
+	try {
+		caCert = readFileSync('/config/ca.crt', 'utf-8');
+	} catch {
+		// CA cert not available
+	}
+
+	const caCertBase64 = Buffer.from(caCert).toString('base64');
+	const sanitizedEmail = email.replace(/[^a-zA-Z0-9@._-]/g, '');
+
+	const kubeconfig = `apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    server: ${CLUSTER_SERVER}
+    certificate-authority-data: ${caCertBase64}
+  name: home-cluster
+contexts:
+- context:
+    cluster: home-cluster
+    user: oidc-${sanitizedEmail}
+  name: home-cluster
+current-context: home-cluster
+users:
+- name: oidc-${sanitizedEmail}
+  user:
+    exec:
+      apiVersion: client.authentication.k8s.io/v1beta1
+      command: kubectl
+      args:
+        - oidc-login
+        - get-token
+        - --oidc-issuer-url=${OIDC_ISSUER}
+        - --oidc-client-id=${OIDC_CLIENT_ID}
+        - --oidc-extra-scope=email
+        - --oidc-extra-scope=profile
+        - --oidc-extra-scope=groups
+      interactiveMode: IfAvailable
+`;
+
+	return new Response(kubeconfig, {
+		headers: {
+			'Content-Type': 'application/yaml',
+			'Content-Disposition': `attachment; filename="kubeconfig-home-cluster.yaml"`
+		}
+	});
+};
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/onboarding/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/onboarding/+page.svelte
@ -0,0 +1,286 @@
+<script>
+	import { page } from '$app/stores';
+	let showNamespaceOwner = $derived($page.url.searchParams.get('role') === 'namespace-owner');
+</script>
+
+<main class="content">
+	<h1>Getting Started</h1>
+	<p>Welcome! Follow these steps to get access to the home Kubernetes cluster.</p>
+
+	<div class="role-tabs">
+		<a href="/onboarding" class:active={!showNamespaceOwner}>General User</a>
+		<a href="/onboarding?role=namespace-owner" class:active={showNamespaceOwner}>Namespace Owner</a>
+	</div>
+
+	<section>
+		<h2>Step 0 — Join the VPN</h2>
+		<p>The cluster is on a private network (<code>10.0.20.0/24</code>). You need VPN access first.</p>
+		<ol>
+			<li>Install <a href="https://tailscale.com/download" target="_blank">Tailscale</a> for your OS</li>
+			<li>Run this in your terminal:
+				<pre>tailscale login --login-server https://headscale.viktorbarzin.me</pre>
+			</li>
+			<li>A browser window will open with a registration URL</li>
+			<li>Send that URL to Viktor via email (<a href="mailto:vbarzin@gmail.com">vbarzin@gmail.com</a>) or Slack</li>
+			<li>Wait for approval (usually within a few hours)</li>
+			<li>Once approved, test: <pre>ping 10.0.20.100</pre></li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>Step 1 — Log in to the portal</h2>
+		<p>Visit <a href="https://k8s-portal.viktorbarzin.me">k8s-portal.viktorbarzin.me</a> and sign in with your Authentik account.</p>
+		<p>If you don't have an account yet, ask Viktor to create one.</p>
+	</section>
+
+	<section>
+		<h2>Step 2 — Set up kubectl</h2>
+		<p>Run one of these commands in your terminal to install everything automatically:</p>
+		<h3>macOS</h3>
+		<p class="prereq">Requires <a href="https://brew.sh" target="_blank">Homebrew</a>. Install it first if you don't have it.</p>
+		<pre>bash &lt;(curl -fsSL https://k8s-portal.viktorbarzin.me/setup/script?os=mac)</pre>
+		<h3>Linux</h3>
+		<pre>bash &lt;(curl -fsSL https://k8s-portal.viktorbarzin.me/setup/script?os=linux)</pre>
+		<h3>Windows</h3>
+		<p>Use <a href="https://learn.microsoft.com/en-us/windows/wsl/install" target="_blank">WSL2</a> and follow the Linux instructions.</p>
+	</section>
+
+	{#if showNamespaceOwner}
+		<section>
+			<h2>Step 3 — Log into Vault</h2>
+			<p>Vault manages your secrets and issues dynamic Kubernetes credentials.</p>
+			<pre>vault login -method=oidc</pre>
+			<p>This opens your browser for Authentik SSO. After login, your token is saved to <code>~/.vault-token</code>.</p>
+		</section>
+
+		<section>
+			<h2>Step 4 — Verify kubectl access</h2>
+			<p>Run this command. It will open your browser for OIDC login the first time:</p>
+			<pre>kubectl get pods -n YOUR_NAMESPACE</pre>
+			<p>You should see an empty list (no resources) or your running pods.</p>
+		</section>
+
+		<section>
+			<h2>Step 5 — Clone the infra repo</h2>
+			<pre>git clone https://github.com/ViktorBarzin/infra.git
+cd infra</pre>
+			<p>This is where all the infrastructure configuration lives. Terraform state is committed as encrypted files.</p>
+		</section>
+
+		<section>
+			<h2>Step 6 — Install tools</h2>
+			<p>You need <code>sops</code> and <code>terragrunt</code> to work with infrastructure state:</p>
+			<h3>macOS</h3>
+			<pre>brew install sops terragrunt</pre>
+			<h3>Linux</h3>
+			<pre># sops
+curl -LO https://github.com/getsops/sops/releases/latest/download/sops-v3.9.4.linux.amd64
+sudo mv sops-*.linux.amd64 /usr/local/bin/sops && sudo chmod +x /usr/local/bin/sops
+
+# terragrunt
+curl -LO https://github.com/gruntwork-io/terragrunt/releases/latest/download/terragrunt_linux_amd64
+sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt && sudo chmod +x /usr/local/bin/terragrunt</pre>
+		</section>
+
+		<section>
+			<h2>Step 7 — Decrypt your state</h2>
+			<p>Terraform state is encrypted with SOPS. Your Vault login gives you access to <strong>only your stacks</strong>.</p>
+			<pre># Make sure you're logged into Vault
+vault login -method=oidc
+
+# Decrypt your stack's state
+scripts/state-sync decrypt YOUR_NAMESPACE
+
+# Plan changes (auto-decrypts before, auto-encrypts after)
+cd stacks/YOUR_NAMESPACE
+../../scripts/tg plan</pre>
+
+			<div class="diagram">
+				<h3>How state encryption works</h3>
+				<div class="flow-diagram">
+					<div class="flow-row">
+						<div class="flow-box accent">vault login -method=oidc</div>
+						<div class="flow-arrow">→</div>
+						<div class="flow-box">Authentik SSO</div>
+						<div class="flow-arrow">→</div>
+						<div class="flow-box accent">~/.vault-token</div>
+					</div>
+					<div class="flow-separator">↓</div>
+					<div class="flow-row">
+						<div class="flow-box accent">scripts/tg plan</div>
+						<div class="flow-arrow">→</div>
+						<div class="flow-box">state-sync decrypt</div>
+						<div class="flow-arrow">→</div>
+						<div class="flow-box">Vault Transit<br/><small>sops-state-YOUR_NS</small></div>
+					</div>
+					<div class="flow-separator">↓</div>
+					<div class="flow-row">
+						<div class="flow-box">terragrunt plan/apply</div>
+						<div class="flow-arrow">→</div>
+						<div class="flow-box">state-sync encrypt</div>
+						<div class="flow-arrow">→</div>
+						<div class="flow-box accent">git commit + push</div>
+					</div>
+				</div>
+			</div>
+
+			<div class="callout info">
+				<strong>Access control:</strong> You can only decrypt state for your own namespaces.
+				Each namespace has its own Vault Transit encryption key. Your Vault policy
+				(<code>sops-user-YOUR_USERNAME</code>) only grants access to your keys.
+			</div>
+		</section>
+
+		<section>
+			<h2>Step 8 — Create your first app stack</h2>
+			<ol>
+				<li>Copy the template: <pre>cp -r stacks/_template stacks/myapp
+mv stacks/myapp/main.tf.example stacks/myapp/main.tf</pre></li>
+				<li>Edit <code>stacks/myapp/main.tf</code> — replace all <code>&lt;placeholders&gt;</code></li>
+				<li>Store secrets in Vault:
+					<pre>vault kv put secret/YOUR_USERNAME/myapp DB_PASSWORD=secret123</pre>
+				</li>
+				<li>Apply your stack:
+					<pre>cd stacks/myapp && ../../scripts/tg apply</pre>
+				</li>
+				<li>Commit encrypted state:
+					<pre>cd ../..
+git add stacks/myapp/ state/stacks/myapp/terraform.tfstate.enc
+git commit -m "add myapp stack"
+git push</pre>
+				</li>
+			</ol>
+		</section>
+
+		<section>
+			<h2>Architecture Overview</h2>
+			<p>Here's how your changes flow through the system:</p>
+
+			<div class="diagram">
+				<h3>Apply workflow</h3>
+				<div class="arch-grid">
+					<div class="arch-col">
+						<div class="arch-header">Your Machine</div>
+						<div class="arch-box">git pull</div>
+						<div class="arch-arrow">↓</div>
+						<div class="arch-box">scripts/tg plan</div>
+						<div class="arch-arrow">↓ <small>auto-decrypt</small></div>
+						<div class="arch-box">scripts/tg apply</div>
+						<div class="arch-arrow">↓ <small>auto-encrypt</small></div>
+						<div class="arch-box">git push</div>
+					</div>
+					<div class="arch-col">
+						<div class="arch-header">Vault</div>
+						<div class="arch-box small">OIDC auth<br/><small>Authentik SSO</small></div>
+						<div class="arch-arrow">↓</div>
+						<div class="arch-box small">Transit decrypt<br/><small>sops-state-*</small></div>
+						<div class="arch-arrow">↓</div>
+						<div class="arch-box small">Transit encrypt<br/><small>per-stack key</small></div>
+					</div>
+					<div class="arch-col">
+						<div class="arch-header">Cluster</div>
+						<div class="arch-box small">K8s API</div>
+						<div class="arch-arrow">↓</div>
+						<div class="arch-box small">Your namespace<br/><small>pods, services</small></div>
+						<div class="arch-arrow">↓</div>
+						<div class="arch-box small">Traefik ingress<br/><small>*.viktorbarzin.me</small></div>
+					</div>
+				</div>
+			</div>
+
+			<div class="diagram">
+				<h3>Security model</h3>
+				<table>
+					<thead><tr><th>Layer</th><th>What</th><th>How</th></tr></thead>
+					<tbody>
+					<tr><td>Authentication</td><td>Who are you?</td><td>Authentik SSO (OIDC) → Vault token</td></tr>
+					<tr><td>Authorization</td><td>What can you access?</td><td>Vault policy (<code>sops-user-*</code>) scoped to your namespaces</td></tr>
+					<tr><td>Encryption at rest</td><td>State in git</td><td>SOPS + Vault Transit (per-stack key)</td></tr>
+					<tr><td>Encryption fallback</td><td>Bootstrap / DR</td><td>age keys (admin only)</td></tr>
+					<tr><td>Network</td><td>Cluster access</td><td>Headscale VPN (private 10.0.20.0/24)</td></tr>
+					</tbody>
+				</table>
+			</div>
+		</section>
+	{:else}
+		<section>
+			<h2>Step 3 — Verify access</h2>
+			<p>Run this command. It will open your browser for login the first time:</p>
+			<pre>kubectl get namespaces</pre>
+			<p>You should see output like:</p>
+			<pre class="output">NAME              STATUS   AGE
+default           Active   200d
+kube-system       Active   200d
+monitoring        Active   200d
+...</pre>
+			<p>If you get a connection error, make sure your VPN is connected (<code>tailscale status</code>).</p>
+		</section>
+
+		<section>
+			<h2>Step 4 — Clone the repo</h2>
+			<pre>git clone https://github.com/ViktorBarzin/infra.git
+cd infra</pre>
+			<p>This is where all the infrastructure configuration lives.</p>
+		</section>
+
+		<section>
+			<h2>Step 5 — Your first change</h2>
+			<ol>
+				<li>Create a branch: <pre>git checkout -b my-first-change</pre></li>
+				<li>Edit a service file (e.g., change an image tag in <code>stacks/echo/main.tf</code>)</li>
+				<li>Commit and push: <pre>git add . && git commit -m "my first change" && git push -u origin my-first-change</pre></li>
+				<li>Open a Pull Request on GitHub</li>
+				<li>Viktor reviews and merges</li>
+				<li>Woodpecker CI automatically applies the change to the cluster</li>
+				<li>Slack notification confirms it worked</li>
+			</ol>
+		</section>
+	{/if}
+</main>
+
+<style>
+	.content { max-width: 768px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
+	.content h1 { border-bottom: 1px solid #e0e0e0; padding-bottom: 0.5rem; }
+	.content h2 { margin-top: 2rem; color: #333; }
+	.content h3 { color: #666; margin: 1rem 0 0.25rem; }
+	.content pre { background: #1e1e1e; color: #d4d4d4; padding: 1rem; border-radius: 6px; overflow-x: auto; }
+	.content pre.output { background: #f5f5f5; color: #333; }
+	.content code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; }
+	.content .prereq { font-size: 0.9rem; color: #666; font-style: italic; }
+	section { margin: 2rem 0; }
+	.role-tabs { display: flex; gap: 0; margin: 1.5rem 0; border-bottom: 2px solid #e0e0e0; }
+	.role-tabs a { padding: 0.5rem 1.5rem; text-decoration: none; color: #666; border-bottom: 2px solid transparent; margin-bottom: -2px; }
+	.role-tabs a.active { color: #333; border-bottom-color: #333; font-weight: 600; }
+	table { border-collapse: collapse; width: 100%; margin: 0.5rem 0; }
+	th, td { border: 1px solid #ddd; padding: 0.5rem; text-align: left; }
+	th { background: #f5f5f5; }
+
+	.callout { padding: 1rem; border-radius: 6px; margin: 1rem 0; }
+	.callout.info { background: #e8f4fd; border-left: 4px solid #2196f3; }
+	.callout.warning { background: #fff3cd; border-left: 4px solid #ffc107; }
+
+	.diagram { background: #fafafa; border: 1px solid #e0e0e0; border-radius: 8px; padding: 1.5rem; margin: 1.5rem 0; }
+	.diagram h3 { margin: 0 0 1rem 0; color: #333; font-size: 0.95rem; text-transform: uppercase; letter-spacing: 0.5px; }
+
+	.flow-diagram { display: flex; flex-direction: column; align-items: center; gap: 0.25rem; }
+	.flow-row { display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap; justify-content: center; }
+	.flow-box { background: white; border: 2px solid #ddd; border-radius: 6px; padding: 0.5rem 1rem; font-family: monospace; font-size: 0.85rem; text-align: center; }
+	.flow-box.accent { border-color: #333; font-weight: 600; }
+	.flow-box small { display: block; color: #888; font-weight: normal; }
+	.flow-arrow { color: #999; font-size: 1.2rem; }
+	.flow-separator { color: #999; font-size: 1.2rem; }
+
+	.arch-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1.5rem; }
+	.arch-col { display: flex; flex-direction: column; align-items: center; gap: 0.25rem; }
+	.arch-header { font-weight: 700; font-size: 0.85rem; text-transform: uppercase; letter-spacing: 0.5px; color: #555; margin-bottom: 0.5rem; padding: 0.25rem 0.75rem; background: #e8e8e8; border-radius: 4px; }
+	.arch-box { background: white; border: 2px solid #ddd; border-radius: 6px; padding: 0.5rem 0.75rem; font-family: monospace; font-size: 0.8rem; text-align: center; width: 100%; box-sizing: border-box; }
+	.arch-box.small { font-size: 0.75rem; }
+	.arch-box small { display: block; color: #888; font-family: monospace; }
+	.arch-arrow { color: #999; font-size: 1rem; }
+
+	@media (max-width: 600px) {
+		.arch-grid { grid-template-columns: 1fr; }
+		.flow-row { flex-direction: column; }
+		.flow-arrow { transform: rotate(90deg); }
+	}
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/services/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/services/+page.svelte
@ -0,0 +1,58 @@
+<main class="content">
+	<h1>Service Catalog</h1>
+	<p>70+ services running on the cluster. Here are the most commonly used:</p>
+
+	<section>
+		<h2>Core Services</h2>
+		<table>
+			<thead><tr><th>Service</th><th>URL</th><th>Description</th></tr></thead>
+			<tbody>
+			<tr><td>Grafana</td><td><a href="https://grafana.viktorbarzin.me">grafana.viktorbarzin.me</a></td><td>Monitoring dashboards</td></tr>
+			<tr><td>Uptime Kuma</td><td><a href="https://uptime.viktorbarzin.me">uptime.viktorbarzin.me</a></td><td>Service uptime monitoring</td></tr>
+			<tr><td>Authentik</td><td><a href="https://authentik.viktorbarzin.me">authentik.viktorbarzin.me</a></td><td>Identity provider (SSO)</td></tr>
+			<tr><td>Woodpecker CI</td><td><a href="https://ci.viktorbarzin.me">ci.viktorbarzin.me</a></td><td>CI/CD pipeline</td></tr>
+		</tbody>
+		</table>
+	</section>
+
+	<section>
+		<h2>User-Facing Services</h2>
+		<table>
+			<thead><tr><th>Service</th><th>URL</th><th>Description</th></tr></thead>
+			<tbody>
+			<tr><td>Nextcloud</td><td><a href="https://nextcloud.viktorbarzin.me">nextcloud.viktorbarzin.me</a></td><td>File storage, calendar, contacts</td></tr>
+			<tr><td>Immich</td><td><a href="https://immich.viktorbarzin.me">immich.viktorbarzin.me</a></td><td>Photo library (Google Photos alternative)</td></tr>
+			<tr><td>Vaultwarden</td><td><a href="https://vault.viktorbarzin.me">vault.viktorbarzin.me</a></td><td>Password manager</td></tr>
+			<tr><td>Paperless-ngx</td><td><a href="https://pdf.viktorbarzin.me">pdf.viktorbarzin.me</a></td><td>Document management</td></tr>
+			<tr><td>Navidrome</td><td><a href="https://music.viktorbarzin.me">music.viktorbarzin.me</a></td><td>Music streaming</td></tr>
+			<tr><td>Tandoor</td><td><a href="https://recipes.viktorbarzin.me">recipes.viktorbarzin.me</a></td><td>Recipe manager</td></tr>
+			<tr><td>Linkwarden</td><td><a href="https://bookmarks.viktorbarzin.me">bookmarks.viktorbarzin.me</a></td><td>Bookmark manager</td></tr>
+		</tbody>
+		</table>
+	</section>
+
+	<section>
+		<h2>Developer Tools</h2>
+		<table>
+			<thead><tr><th>Service</th><th>URL</th><th>Description</th></tr></thead>
+			<tbody>
+			<tr><td>Forgejo</td><td><a href="https://forgejo.viktorbarzin.me">forgejo.viktorbarzin.me</a></td><td>Git server (Gitea fork)</td></tr>
+			<tr><td>CyberChef</td><td><a href="https://cyberchef.viktorbarzin.me">cyberchef.viktorbarzin.me</a></td><td>Data transformation tool</td></tr>
+			<tr><td>Excalidraw</td><td><a href="https://draw.viktorbarzin.me">draw.viktorbarzin.me</a></td><td>Whiteboard drawing</td></tr>
+			<tr><td>PrivateBin</td><td><a href="https://paste.viktorbarzin.me">paste.viktorbarzin.me</a></td><td>Encrypted paste bin</td></tr>
+			<tr><td>JSON Crack</td><td><a href="https://jsoncrack.viktorbarzin.me">jsoncrack.viktorbarzin.me</a></td><td>JSON visualizer</td></tr>
+		</tbody>
+		</table>
+	</section>
+</main>
+
+<style>
+	.content { max-width: 768px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
+	.content h1 { border-bottom: 1px solid #e0e0e0; padding-bottom: 0.5rem; }
+	.content h2 { margin-top: 2rem; color: #333; }
+	section { margin: 2rem 0; }
+	table { border-collapse: collapse; width: 100%; }
+	th, td { border: 1px solid #ddd; padding: 0.5rem; text-align: left; }
+	th { background: #f5f5f5; }
+	a { color: #1a73e8; }
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/setup/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/setup/+page.svelte
@ -0,0 +1,69 @@
+<main>
+	<h1>Setup Instructions</h1>
+
+	<section>
+		<h2>Quick Setup (one command)</h2>
+		<p>Run this in your terminal to install everything and configure kubectl automatically:</p>
+		<h3>macOS</h3>
+		<pre>bash &lt;(curl -fsSL https://k8s-portal.viktorbarzin.me/setup/script?os=mac)</pre>
+		<h3>Linux</h3>
+		<pre>bash &lt;(curl -fsSL https://k8s-portal.viktorbarzin.me/setup/script?os=linux)</pre>
+	</section>
+
+	<section>
+		<h2>Manual Setup</h2>
+
+		<h3>1. Install kubectl</h3>
+		<h4>macOS</h4>
+		<pre>brew install kubectl</pre>
+		<h4>Linux</h4>
+		<pre>curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+chmod +x kubectl && sudo mv kubectl /usr/local/bin/</pre>
+
+		<h3>2. Install kubelogin (OIDC plugin)</h3>
+		<h4>macOS</h4>
+		<pre>brew install int128/kubelogin/kubelogin</pre>
+		<h4>Linux</h4>
+		<pre>curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip
+unzip kubelogin_linux_amd64.zip && sudo mv kubelogin /usr/local/bin/kubectl-oidc_login
+rm kubelogin_linux_amd64.zip</pre>
+
+		<h3>3. Download and use your kubeconfig</h3>
+		<pre>
+mkdir -p ~/.kube
+
+# Download from the portal (requires auth cookie from browser)
+# Or use the download button on the portal homepage
+
+# Set the KUBECONFIG environment variable
+export KUBECONFIG=~/.kube/config-home
+
+# Test access (opens browser for login)
+kubectl get namespaces
+		</pre>
+	</section>
+
+	<p><a href="/">&#8592; Back to portal</a></p>
+</main>
+
+<style>
+	main {
+		max-width: 640px;
+		margin: 2rem auto;
+		font-family: system-ui;
+	}
+	pre {
+		background: #1e1e1e;
+		color: #d4d4d4;
+		padding: 1rem;
+		border-radius: 6px;
+		overflow-x: auto;
+	}
+	section {
+		margin: 2rem 0;
+	}
+	h4 {
+		margin: 0.5rem 0 0.25rem;
+		color: #666;
+	}
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/setup/script/+server.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/setup/script/+server.ts
@ -0,0 +1,266 @@
+import type { RequestHandler } from './$types';
+import { readFileSync } from 'fs';
+
+const CLUSTER_SERVER = 'https://10.0.20.100:6443';
+const OIDC_ISSUER = 'https://authentik.viktorbarzin.me/application/o/kubernetes/';
+const OIDC_CLIENT_ID = 'kubernetes';
+
+export const GET: RequestHandler = async ({ url }) => {
+	const os = url.searchParams.get('os') || 'mac';
+
+	let caCert = '';
+	try {
+		caCert = readFileSync('/config/ca.crt', 'utf-8');
+	} catch {
+		// CA cert not available
+	}
+	const caCertBase64 = Buffer.from(caCert).toString('base64');
+
+	const kubeconfigContent = `apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    server: ${CLUSTER_SERVER}
+    certificate-authority-data: ${caCertBase64}
+  name: home-cluster
+contexts:
+- context:
+    cluster: home-cluster
+    user: oidc-user
+  name: home-cluster
+current-context: home-cluster
+users:
+- name: oidc-user
+  user:
+    exec:
+      apiVersion: client.authentication.k8s.io/v1beta1
+      command: kubectl
+      args:
+        - oidc-login
+        - get-token
+        - --oidc-issuer-url=${OIDC_ISSUER}
+        - --oidc-client-id=${OIDC_CLIENT_ID}
+        - --oidc-extra-scope=email
+        - --oidc-extra-scope=profile
+        - --oidc-extra-scope=groups
+      interactiveMode: IfAvailable`;
+
+	let script: string;
+
+	if (os === 'linux') {
+		script = `#!/bin/bash
+set -e
+
+echo "=== Kubernetes Cluster Setup ==="
+echo ""
+
+# Use sudo if available, otherwise install directly (e.g. in containers running as root)
+SUDO=""
+if [ "$(id -u)" -ne 0 ] && command -v sudo &>/dev/null; then
+    SUDO="sudo"
+fi
+
+# Determine install directory
+INSTALL_DIR="/usr/local/bin"
+if [ ! -w "\$INSTALL_DIR" ] && [ -z "\$SUDO" ]; then
+    INSTALL_DIR="\$HOME/.local/bin"
+    mkdir -p "\$INSTALL_DIR"
+    export PATH="\$INSTALL_DIR:\$PATH"
+fi
+
+# Install kubectl
+if command -v kubectl &>/dev/null; then
+    echo "[OK] kubectl already installed"
+else
+    echo "[..] Installing kubectl..."
+    KUBECTL_VERSION=\$(curl -L -s https://dl.k8s.io/release/stable.txt)
+    curl -fsSLO "https://dl.k8s.io/release/\${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
+    chmod +x kubectl && \$SUDO mv kubectl "\$INSTALL_DIR/"
+    echo "[OK] kubectl installed"
+fi
+
+# Install kubelogin
+if command -v kubectl-oidc_login &>/dev/null; then
+    echo "[OK] kubelogin already installed"
+else
+    echo "[..] Installing kubelogin..."
+    KUBELOGIN_VERSION=\$(curl -fsSL -o /dev/null -w "%{url_effective}" https://github.com/int128/kubelogin/releases/latest | grep -o '[^/]*\$')
+    curl -fsSLO "https://github.com/int128/kubelogin/releases/download/\${KUBELOGIN_VERSION}/kubelogin_linux_amd64.zip"
+    unzip -o kubelogin_linux_amd64.zip kubelogin -d /tmp
+    \$SUDO mv /tmp/kubelogin "\$INSTALL_DIR/kubectl-oidc_login"
+    rm -f kubelogin_linux_amd64.zip
+    echo "[OK] kubelogin installed"
+fi
+
+# Install kubeseal
+if command -v kubeseal &>/dev/null; then
+    echo "[OK] kubeseal already installed"
+else
+    echo "[..] Installing kubeseal..."
+    KUBESEAL_VERSION=\$(curl -fsSL -o /dev/null -w "%{url_effective}" https://github.com/bitnami-labs/sealed-secrets/releases/latest | grep -o '[^/]*\$')
+    curl -fsSLO "https://github.com/bitnami-labs/sealed-secrets/releases/download/\${KUBESEAL_VERSION}/kubeseal-\${KUBESEAL_VERSION#v}-linux-amd64.tar.gz"
+    tar -xzf "kubeseal-\${KUBESEAL_VERSION#v}-linux-amd64.tar.gz" kubeseal
+    \$SUDO mv kubeseal "\$INSTALL_DIR/"
+    rm -f "kubeseal-\${KUBESEAL_VERSION#v}-linux-amd64.tar.gz"
+    echo "[OK] kubeseal installed"
+fi
+
+# Install Vault CLI
+if command -v vault &>/dev/null; then
+    echo "[OK] vault already installed"
+else
+    echo "[..] Installing Vault CLI..."
+    VAULT_VERSION="1.18.1"
+    curl -fsSLO "https://releases.hashicorp.com/vault/\${VAULT_VERSION}/vault_\${VAULT_VERSION}_linux_amd64.zip"
+    unzip -o "vault_\${VAULT_VERSION}_linux_amd64.zip" vault -d /tmp
+    \$SUDO mv /tmp/vault "\$INSTALL_DIR/"
+    rm -f "vault_\${VAULT_VERSION}_linux_amd64.zip"
+    echo "[OK] vault installed"
+fi
+
+# Install Terragrunt
+if command -v terragrunt &>/dev/null; then
+    echo "[OK] terragrunt already installed"
+else
+    echo "[..] Installing terragrunt..."
+    TG_VERSION=\$(curl -fsSL -o /dev/null -w "%{url_effective}" https://github.com/gruntwork-io/terragrunt/releases/latest | grep -o '[^/]*\$')
+    curl -fsSLO "https://github.com/gruntwork-io/terragrunt/releases/download/\${TG_VERSION}/terragrunt_linux_amd64"
+    chmod +x terragrunt_linux_amd64
+    \$SUDO mv terragrunt_linux_amd64 "\$INSTALL_DIR/terragrunt"
+    echo "[OK] terragrunt installed"
+fi
+
+# Install Terraform
+if command -v terraform &>/dev/null; then
+    echo "[OK] terraform already installed"
+else
+    echo "[..] Installing terraform..."
+    TF_VERSION="1.9.8"
+    curl -fsSLO "https://releases.hashicorp.com/terraform/\${TF_VERSION}/terraform_\${TF_VERSION}_linux_amd64.zip"
+    unzip -o "terraform_\${TF_VERSION}_linux_amd64.zip" terraform -d /tmp
+    \$SUDO mv /tmp/terraform "\$INSTALL_DIR/"
+    rm -f "terraform_\${TF_VERSION}_linux_amd64.zip"
+    echo "[OK] terraform installed"
+fi
+
+# Write kubeconfig
+mkdir -p ~/.kube
+cat > ~/.kube/config-home << 'KUBECONFIG_EOF'
+${kubeconfigContent}
+KUBECONFIG_EOF
+echo "[OK] Kubeconfig written to ~/.kube/config-home"
+
+# Add KUBECONFIG to shell profile
+SHELL_RC=~/.bashrc
+[ -f ~/.zshrc ] && SHELL_RC=~/.zshrc
+if ! grep -q 'config-home' "\$SHELL_RC" 2>/dev/null; then
+    echo 'export KUBECONFIG=~/.kube/config-home' >> "\$SHELL_RC"
+    echo "[OK] Added KUBECONFIG to \$SHELL_RC"
+fi
+export KUBECONFIG=~/.kube/config-home
+
+echo ""
+echo "=== Setup complete! ==="
+echo ""
+echo "Run 'kubectl get namespaces' to test (opens browser for login)."
+echo "You may need to restart your shell or run: export KUBECONFIG=~/.kube/config-home"
+`;
+	} else {
+		script = `#!/bin/bash
+set -e
+
+echo "=== Kubernetes Cluster Setup ==="
+echo ""
+
+# Check for Homebrew
+if ! command -v brew &>/dev/null; then
+    echo "[!!] Homebrew not found. Install it first:"
+    echo '     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
+    exit 1
+fi
+
+# Install kubectl
+if command -v kubectl &>/dev/null; then
+    echo "[OK] kubectl already installed ($(kubectl version --client -o json 2>/dev/null | grep -o '"gitVersion":"[^"]*"' | cut -d'"' -f4))"
+else
+    echo "[..] Installing kubectl..."
+    brew install kubectl
+    echo "[OK] kubectl installed"
+fi
+
+# Install kubelogin
+if command -v kubectl-oidc_login &>/dev/null; then
+    echo "[OK] kubelogin already installed"
+else
+    echo "[..] Installing kubelogin..."
+    brew install int128/kubelogin/kubelogin
+    echo "[OK] kubelogin installed"
+fi
+
+# Install kubeseal
+if command -v kubeseal &>/dev/null; then
+    echo "[OK] kubeseal already installed"
+else
+    echo "[..] Installing kubeseal..."
+    brew install kubeseal
+    echo "[OK] kubeseal installed"
+fi
+
+# Install Vault CLI
+if command -v vault &>/dev/null; then
+    echo "[OK] vault already installed"
+else
+    echo "[..] Installing Vault CLI..."
+    brew tap hashicorp/tap
+    brew install hashicorp/tap/vault
+    echo "[OK] vault installed"
+fi
+
+# Install Terragrunt
+if command -v terragrunt &>/dev/null; then
+    echo "[OK] terragrunt already installed"
+else
+    echo "[..] Installing terragrunt..."
+    brew install terragrunt
+    echo "[OK] terragrunt installed"
+fi
+
+# Install Terraform
+if command -v terraform &>/dev/null; then
+    echo "[OK] terraform already installed"
+else
+    echo "[..] Installing terraform..."
+    brew install hashicorp/tap/terraform
+    echo "[OK] terraform installed"
+fi
+
+# Write kubeconfig
+mkdir -p ~/.kube
+cat > ~/.kube/config-home << 'KUBECONFIG_EOF'
+${kubeconfigContent}
+KUBECONFIG_EOF
+echo "[OK] Kubeconfig written to ~/.kube/config-home"
+
+# Add KUBECONFIG to shell profile
+SHELL_RC=~/.zshrc
+[ ! -f ~/.zshrc ] && SHELL_RC=~/.bashrc
+if ! grep -q 'config-home' "\$SHELL_RC" 2>/dev/null; then
+    echo 'export KUBECONFIG=~/.kube/config-home' >> "\$SHELL_RC"
+    echo "[OK] Added KUBECONFIG to \$SHELL_RC"
+fi
+export KUBECONFIG=~/.kube/config-home
+
+echo ""
+echo "=== Setup complete! ==="
+echo ""
+echo "Run 'kubectl get namespaces' to test (opens browser for login)."
+echo "You may need to restart your shell or run: export KUBECONFIG=~/.kube/config-home"
+`;
+	}
+
+	return new Response(script, {
+		headers: {
+			'Content-Type': 'text/plain; charset=utf-8'
+		}
+	});
+};
--- a/stacks/k8s-portal/modules/k8s-portal/files/src/routes/troubleshooting/+page.svelte
+++ b/stacks/k8s-portal/modules/k8s-portal/files/src/routes/troubleshooting/+page.svelte
@ -0,0 +1,63 @@
+<main class="content">
+	<h1>Troubleshooting</h1>
+
+	<section>
+		<h2>"kubectl can't connect to the server"</h2>
+		<ol>
+			<li>Check your VPN: <code>tailscale status</code> — should show "connected"</li>
+			<li>Check KUBECONFIG: <code>echo $KUBECONFIG</code> — should be <code>~/.kube/config-home</code></li>
+			<li>Test connectivity: <code>ping 10.0.20.100</code></li>
+			<li>If ping works but kubectl doesn't, re-run the <a href="/setup">setup script</a></li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>"Forbidden" or "Permission denied"</h2>
+		<p>You may not have access to that namespace. Your access is scoped to specific namespaces.</p>
+		<p>Try: <code>kubectl get namespaces</code> to see which namespaces you can access.</p>
+		<p>Need access to another namespace? Ask Viktor.</p>
+	</section>
+
+	<section>
+		<h2>"Pod is CrashLoopBackOff"</h2>
+		<ol>
+			<li>Check pod logs: <code>kubectl logs -n &lt;namespace&gt; &lt;pod-name&gt; --tail=50</code></li>
+			<li>Check previous crash: <code>kubectl logs -n &lt;namespace&gt; &lt;pod-name&gt; --previous</code></li>
+			<li>Check events: <code>kubectl describe pod -n &lt;namespace&gt; &lt;pod-name&gt;</code></li>
+			<li>Common causes: OOMKilled (need more memory), bad config, database connection failure</li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>"PR CI failed"</h2>
+		<ol>
+			<li>Check the Woodpecker CI dashboard: <a href="https://ci.viktorbarzin.me">ci.viktorbarzin.me</a></li>
+			<li>Read the build logs — the error is usually at the bottom</li>
+			<li>Fix the issue, commit, and push — CI will re-run</li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>"I need a new secret / database password"</h2>
+		<p>Secrets are managed by Viktor in an encrypted file. You cannot add them yourself.</p>
+		<ol>
+			<li>Comment on your PR: "Need DB password for &lt;service&gt;"</li>
+			<li>Viktor adds the secret and pushes to your branch</li>
+			<li>Reference it as <code>var.&lt;service&gt;_db_password</code> in your Terraform</li>
+		</ol>
+	</section>
+
+	<section>
+		<h2>Still stuck?</h2>
+		<p>Email Viktor at <a href="mailto:vbarzin@gmail.com">vbarzin@gmail.com</a> or message on Slack.</p>
+	</section>
+</main>
+
+<style>
+	.content { max-width: 768px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, -apple-system, sans-serif; line-height: 1.6; }
+	.content h1 { border-bottom: 1px solid #e0e0e0; padding-bottom: 0.5rem; }
+	.content h2 { margin-top: 2rem; color: #333; }
+	.content pre { background: #1e1e1e; color: #d4d4d4; padding: 1rem; border-radius: 6px; overflow-x: auto; }
+	.content code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; }
+	section { margin: 2rem 0; }
+</style>
--- a/stacks/k8s-portal/modules/k8s-portal/files/static/robots.txt
+++ b/stacks/k8s-portal/modules/k8s-portal/files/static/robots.txt
@ -0,0 +1,3 @@
+# allow crawling everything by default
+User-agent: *
+Disallow:
--- a/stacks/k8s-portal/modules/k8s-portal/files/svelte.config.js
+++ b/stacks/k8s-portal/modules/k8s-portal/files/svelte.config.js
@ -0,0 +1,10 @@
+import adapter from '@sveltejs/adapter-node';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
--- a/stacks/k8s-portal/modules/k8s-portal/files/tsconfig.json
+++ b/stacks/k8s-portal/modules/k8s-portal/files/tsconfig.json
@ -0,0 +1,20 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"rewriteRelativeImportExtensions": true,
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// To make changes to top-level options such as include and exclude, we recommend extending
+	// the generated config; see https://svelte.dev/docs/kit/configuration#typescript
+}
--- a/stacks/k8s-portal/modules/k8s-portal/files/vite.config.ts
+++ b/stacks/k8s-portal/modules/k8s-portal/files/vite.config.ts
@ -0,0 +1,6 @@
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [sveltekit()]
+});
--- a/stacks/k8s-portal/modules/k8s-portal/main.tf
+++ b/stacks/k8s-portal/modules/k8s-portal/main.tf
@ -0,0 +1,176 @@
+variable "tls_secret_name" {}
+variable "tier" { type = string }
+variable "k8s_ca_cert" {
+  type    = string
+  default = ""
+}
+
+resource "kubernetes_namespace" "k8s_portal" {
+  metadata {
+    name = "k8s-portal"
+    labels = {
+      tier = var.tier
+      "keel.sh/enrolled" = "true"
+    }
+  }
+  lifecycle {
+    # KYVERNO_LIFECYCLE_V1: goldilocks-vpa-auto-mode ClusterPolicy stamps this label on every namespace
+    ignore_changes = [metadata[0].labels["goldilocks.fairwinds.com/vpa-update-mode"]]
+  }
+}
+
+module "tls_secret" {
+  source          = "../../../../modules/kubernetes/setup_tls_secret"
+  namespace       = kubernetes_namespace.k8s_portal.metadata[0].name
+  tls_secret_name = var.tls_secret_name
+}
+
+resource "kubernetes_config_map" "k8s_portal_config" {
+  metadata {
+    name      = "k8s-portal-config"
+    namespace = kubernetes_namespace.k8s_portal.metadata[0].name
+  }
+
+  data = {
+    "ca.crt" = var.k8s_ca_cert
+  }
+}
+
+resource "kubernetes_deployment" "k8s_portal" {
+  metadata {
+    name      = "k8s-portal"
+    namespace = kubernetes_namespace.k8s_portal.metadata[0].name
+    labels = {
+      app  = "k8s-portal"
+      tier = var.tier
+    }
+  }
+
+  spec {
+    replicas = 1
+    strategy {
+      type = "Recreate"
+    }
+    revision_history_limit = 3
+    selector {
+      match_labels = {
+        app = "k8s-portal"
+      }
+    }
+
+    template {
+      metadata {
+        labels = {
+          app = "k8s-portal"
+        }
+      }
+
+      spec {
+        container {
+          name  = "portal"
+          image = "viktorbarzin/k8s-portal:latest"
+          port {
+            container_port = 3000
+          }
+
+          volume_mount {
+            name       = "config"
+            mount_path = "/config/ca.crt"
+            sub_path   = "ca.crt"
+            read_only  = true
+          }
+          volume_mount {
+            name       = "user-roles"
+            mount_path = "/config/users.json"
+            sub_path   = "users.json"
+            read_only  = true
+          }
+          resources {
+            requests = {
+              cpu    = "10m"
+              memory = "128Mi"
+            }
+            limits = {
+              memory = "128Mi"
+            }
+          }
+        }
+
+        volume {
+          name = "config"
+          config_map {
+            name = kubernetes_config_map.k8s_portal_config.metadata[0].name
+          }
+        }
+        volume {
+          name = "user-roles"
+          config_map {
+            name = "k8s-user-roles"
+          }
+        }
+        dns_config {
+          option {
+            name  = "ndots"
+            value = "2"
+          }
+        }
+      }
+    }
+  }
+  lifecycle {
+    # DRIFT_WORKAROUND: CI pipeline owns image tag (kubectl set image from Woodpecker/GHA); Kyverno mutates dns_config for ndots. Reviewed 2026-04-18.
+    ignore_changes = [
+      spec[0].template[0].spec[0].dns_config,         # KYVERNO_LIFECYCLE_V1
+      spec[0].template[0].spec[0].container[0].image, # CI updates image tag
+    ]
+  }
+}
+
+resource "kubernetes_service" "k8s_portal" {
+  metadata {
+    name      = "k8s-portal"
+    namespace = kubernetes_namespace.k8s_portal.metadata[0].name
+  }
+
+  spec {
+    selector = {
+      app = "k8s-portal"
+    }
+    port {
+      port        = 80
+      target_port = 3000
+    }
+  }
+}
+
+module "ingress" {
+  source          = "../../../../modules/kubernetes/ingress_factory"
+  dns_type        = "non-proxied"
+  namespace       = kubernetes_namespace.k8s_portal.metadata[0].name
+  name            = "k8s-portal"
+  tls_secret_name = var.tls_secret_name
+  auth            = "required" # Require Authentik login
+  extra_annotations = {
+    "gethomepage.dev/enabled"      = "true"
+    "gethomepage.dev/name"         = "K8s Portal"
+    "gethomepage.dev/description"  = "Kubernetes portal"
+    "gethomepage.dev/icon"         = "kubernetes.png"
+    "gethomepage.dev/group"        = "Core Platform"
+    "gethomepage.dev/pod-selector" = ""
+  }
+}
+
+# Unprotected ingress for the setup script and agent endpoint (needs to be
+# curl-able without auth). `auth = "public"` would 302+cookie-dance on
+# first visit, breaking automation that doesn't preserve cookies.
+module "ingress_setup_script" {
+  source          = "../../../../modules/kubernetes/ingress_factory"
+  namespace       = kubernetes_namespace.k8s_portal.metadata[0].name
+  name            = "k8s-portal-setup"
+  host            = "k8s-portal"
+  service_name    = "k8s-portal"
+  ingress_path    = ["/setup/script", "/agent"]
+  tls_secret_name = var.tls_secret_name
+  # auth = "none": Setup script + agent endpoint must be curl-able without auth (no cookies preserved in automation).
+  auth            = "none"
+}
				`@ -0,0 +1 @@`
				<svg xmlns="http://www.w3.org/2000/svg" width="107" height="128" viewBox="0 0 107 128"><title>svelte-logo</title><path d="M94.157 22.819c-10.4-14.885-30.94-19.297-45.792-9.835L22.282 29.608A29.92 29.92 0 0 0 8.764 49.65a31.5 31.5 0 0 0 3.108 20.231 30 30 0 0 0-4.477 11.183 31.9 31.9 0 0 0 5.448 24.116c10.402 14.887 30.942 19.297 45.791 9.835l26.083-16.624A29.92 29.92 0 0 0 98.235 78.35a31.53 31.53 0 0 0-3.105-20.232 30 30 0 0 0 4.474-11.182 31.88 31.88 0 0 0-5.447-24.116" style="fill:#ff3e00"/><path d="M45.817 106.582a20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.503 18 18 0 0 1 .624-2.435l.49-1.498 1.337.981a33.6 33.6 0 0 0 10.203 5.098l.97.294-.09.968a5.85 5.85 0 0 0 1.052 3.878 6.24 6.24 0 0 0 6.695 2.485 5.8 5.8 0 0 0 1.603-.704L69.27 76.28a5.43 5.43 0 0 0 2.45-3.631 5.8 5.8 0 0 0-.987-4.371 6.24 6.24 0 0 0-6.698-2.487 5.7 5.7 0 0 0-1.6.704l-9.953 6.345a19 19 0 0 1-5.296 2.326 20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.502 17.99 17.99 0 0 1 8.13-12.052l26.081-16.623a19 19 0 0 1 5.3-2.329 20.72 20.72 0 0 1 22.237 8.243 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-.624 2.435l-.49 1.498-1.337-.98a33.6 33.6 0 0 0-10.203-5.1l-.97-.294.09-.968a5.86 5.86 0 0 0-1.052-3.878 6.24 6.24 0 0 0-6.696-2.485 5.8 5.8 0 0 0-1.602.704L37.73 51.72a5.42 5.42 0 0 0-2.449 3.63 5.79 5.79 0 0 0 .986 4.372 6.24 6.24 0 0 0 6.698 2.486 5.8 5.8 0 0 0 1.602-.704l9.952-6.342a19 19 0 0 1 5.295-2.328 20.72 20.72 0 0 1 22.237 8.242 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-8.13 12.053l-26.081 16.622a19 19 0 0 1-5.3 2.328" style="fill:#fff"/></svg>
				`@ -0,0 +1 @@`
				// place files you want to import through the `$lib` alias in this folder.