docs: add tubco setup runbook

backend/workflows/templates/workflows/developer_handbook.html

@@ -38,6 +38,7 @@
       <a href="#hosts">Hosts & Domains</a>
       <a href="#cicd">CI/CD</a>
       <a href="#deploy">Deployment</a>
+      <a href="#tubco">TUBCO Setup</a>
       <a href="#commands">Commands</a>
       <a href="#troubleshooting">Troubleshooting</a>
       <a href="#security">Security</a>
@@ -661,6 +662,84 @@ lxc.mount.entry: /dev/null sys/module/apparmor/parameters/enabled none bind 0 0<
       <li>Take a snapshot commit before major next-phase work</li>
     </ol>
 
+    <h2 id="tubco">18b) TUBCO Customer Setup</h2>
+    <div class="box">
+      <h3>What this branch is for</h3>
+      <ul>
+        <li><code>release/tubco-v1</code> is the frozen TUBCO customer branch.</li>
+        <li>It should receive only approved bug fixes, security updates, and UI improvements.</li>
+        <li>Do not deploy TUBCO from <code>develop</code> or <code>main</code>.</li>
+      </ul>
+    </div>
+    <div class="box">
+      <h3>First-time customer setup</h3>
+      <ol>
+        <li>Check out <code>release/tubco-v1</code>.</li>
+        <li>Create <code>.env.prod</code> on the target server.</li>
+        <li>Run the destructive reset/bootstrap helper from the Mac.</li>
+        <li>Import the intended TUBCO config baseline.</li>
+        <li>Verify <code>https://portal.tub.co/healthz/</code>.</li>
+      </ol>
+      <pre><code>git checkout release/tubco-v1
+RESET_CONFIRM=RESET \
+EXPECTED_BRANCH=release/tubco-v1 \
+DEPLOY_HOST=root@&lt;customer-host&gt; \
+DEPLOY_PATH=/opt/workdock \
+REMOTE_ENV_FILE=.env.prod \
+HEALTH_URL=https://portal.tub.co/healthz/ \
+RUN_DJANGO_CHECK=1 \
+./scripts/reset_stack_from_mac.sh</code></pre>
+    </div>
+    <div class="box">
+      <h3>Required production env values</h3>
+      <pre><code>APP_DOMAIN=portal.tub.co
+APP_BASE_URL=https://portal.tub.co
+DJANGO_DEBUG=0
+DJANGO_SECURE_COOKIES=1
+DJANGO_SECURE_SSL_REDIRECT=1</code></pre>
+      <p>The customer server also needs strong values for <code>DJANGO_SECRET_KEY</code> and <code>POSTGRES_PASSWORD</code>.</p>
+    </div>
+    <div class="box">
+      <h3>Config baseline import</h3>
+      <p>Export the intended local baseline:</p>
+      <pre><code>docker compose exec -T web python manage.py export_portal_app_config --output /tmp/portal-app-config.json
+docker compose exec -T web python manage.py export_portal_deployment_config --output /tmp/portal-deployment-config.json
+docker compose cp web:/tmp/portal-app-config.json /tmp/portal-app-config.json
+docker compose cp web:/tmp/portal-deployment-config.json /tmp/portal-deployment-config.json</code></pre>
+      <p>Copy the payloads to the customer server and then into the running web container:</p>
+      <pre><code>scp -4 /tmp/portal-app-config.json /tmp/portal-deployment-config.json root@&lt;customer-host&gt;:/opt/workdock/
+ssh -4 root@&lt;customer-host&gt; '
+docker cp /opt/workdock/portal-app-config.json workdock-web-1:/tmp/portal-app-config.json &amp;&amp;
+docker cp /opt/workdock/portal-deployment-config.json workdock-web-1:/tmp/portal-deployment-config.json
+'</code></pre>
+      <p>Dry-run first, then apply:</p>
+      <pre><code>ssh -4 root@&lt;customer-host&gt; '
+docker exec workdock-web-1 python manage.py import_portal_app_config /tmp/portal-app-config.json --dry-run &amp;&amp;
+docker exec workdock-web-1 python manage.py import_portal_deployment_config /tmp/portal-deployment-config.json --dry-run
+'
+
+ssh -4 root@&lt;customer-host&gt; '
+docker exec workdock-web-1 python manage.py import_portal_app_config /tmp/portal-app-config.json &amp;&amp;
+docker exec workdock-web-1 python manage.py import_portal_deployment_config /tmp/portal-deployment-config.json
+'</code></pre>
+      <p>Uploaded assets such as logo, favicon, and PDF letterhead are still separate media and need explicit upload.</p>
+    </div>
+    <div class="box">
+      <h3>Normal TUBCO updates</h3>
+      <p>When you intentionally want to update the customer branch remote:</p>
+      <pre><code>./scripts/git_remote_target.sh status
+./scripts/git_remote_target.sh push-tubco release/tubco-v1</code></pre>
+      <p>Use a TUBCO personal access token stored in the macOS keychain, not a reusable account password.</p>
+    </div>
+    <div class="box">
+      <h3>Customer role boundary</h3>
+      <ul>
+        <li>TUBCO should work primarily with <code>Super Admin</code> and below.</li>
+        <li>In the customer branch, <code>Super Admin</code> can access Branding and Company Config.</li>
+        <li><code>App Registry</code>, <code>Trial Management</code>, and the Django admin link remain platform-level.</li>
+      </ul>
+    </div>
+
     <h2 id="commands">19) Command Reference</h2>
     <div class="box">
       <h3>Local development</h3>
@@ -700,6 +779,21 @@ RUN_DJANGO_CHECK=1 \
 ./scripts/reset_stack_from_mac.sh</code></pre>
       <p>Use the second form for a customer setup from scratch. This is destructive and removes database/media/static/backups before bootstrapping again.</p>
     </div>
+    <div class="box">
+      <h3>TUBCO setup</h3>
+      <pre><code>git checkout release/tubco-v1
+RESET_CONFIRM=RESET \
+EXPECTED_BRANCH=release/tubco-v1 \
+DEPLOY_HOST=root@&lt;customer-host&gt; \
+DEPLOY_PATH=/opt/workdock \
+REMOTE_ENV_FILE=.env.prod \
+HEALTH_URL=https://portal.tub.co/healthz/ \
+RUN_DJANGO_CHECK=1 \
+./scripts/reset_stack_from_mac.sh</code></pre>
+      <p>Rebuild a fresh TUBCO environment from the customer branch.</p>
+      <pre><code>./scripts/git_remote_target.sh push-tubco release/tubco-v1</code></pre>
+      <p>Push an explicitly approved customer update to the TUBCO remote.</p>
+    </div>
     <div class="box">
       <h3>Production deployment</h3>
       <pre><code>./scripts/deploy_prod_from_mac.sh</code></pre>