@p10i/create-nestbox 0.1.0

package/home/code/scripts.js

@@ -0,0 +1,3 @@
+import 'github-markdown-css/github-markdown.css';
+import 'bootstrap/dist/css/bootstrap.css';
+import 'bootstrap';

package/home/code/styles.css

@@ -0,0 +1,36 @@
+/**
+ * Globally applied styles.
+ */
+body {
+    padding: 4.75rem 2rem 2rem;
+}
+
+@media (max-width: 575.98px) {
+    body {
+        padding: 4.25rem 1rem 1rem;
+    }
+}
+
+.markdown-body {
+    max-width: 1920px;
+    margin: 0 auto !important;
+}
+
+/* Push the heading-permalink anchor to the right edge of the heading. */
+.markdown-body :is(h1, h2, h3, h4, h5, h6) {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 1rem;
+}
+
+.markdown-body .heading-permalink {
+    margin-left: auto;
+    opacity: 0.4;
+    text-decoration: none;
+    font-size: 0.8em;
+}
+
+.markdown-body .heading-permalink:hover {
+    opacity: 1;
+}

package/home/configs/nginx/nginx.conf

@@ -0,0 +1,199 @@
+include /etc/nginx/modules/*.conf;
+
+worker_processes  1;
+error_log /dev/stderr notice;
+pid /run/nginx/nginx.pid;
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+    access_log    /dev/stdout;
+
+    nchan_shared_memory_size 16M;
+    limit_conn_zone $binary_remote_addr zone=nestbox_events:1m;
+
+    map $http_x_forwarded_proto $nestbox_public_scheme {
+        ~*^https(?:,|$) https;
+        ~*^http(?:,|$) http;
+        default $scheme;
+    }
+
+    map $http_host $agent_host {
+        ~^localhost(:\d+)?$ agent.localhost$1;
+        ~^127\.0\.0\.1(:\d+)?$ agent.localhost$1;
+        default agent.$http_host;
+    }
+
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+
+    sendfile        on;
+    keepalive_timeout  65;
+
+    server {
+        listen 80 default_server;
+
+        root /var/www/html;
+        index index.php;
+        error_page 404 /404.php;
+
+        # Super-documents are trusted and may contain inline scripts and styles.
+        add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; base-uri 'self'; frame-ancestors 'self'" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+        # Nestbox is actively edited; pages and generated bundles must not
+        # remain stale in the browser cache.
+        add_header Cache-Control "no-store" always;
+
+        location = /_nestbox/health {
+            include /etc/nginx/fastcgi_params;
+            fastcgi_pass php-fpm:9000;
+            fastcgi_intercept_errors on;
+            fastcgi_param SCRIPT_FILENAME /sources/php/index.php;
+        }
+
+        location = /_nestbox/events {
+            if ($arg_topics !~ "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}(?::[A-Za-z0-9][A-Za-z0-9._/-]{0,63})*(?::\*)?(?:,[A-Za-z0-9][A-Za-z0-9._/-]{0,63}(?::[A-Za-z0-9][A-Za-z0-9._/-]{0,63})*(?::\*)?){0,15}$") {
+                return 400;
+            }
+
+            limit_conn nestbox_events 6;
+            nchan_subscriber;
+            nchan_channel_group_accounting on;
+            nchan_channel_group nestbox;
+            nchan_channel_id $arg_topics;
+            nchan_channel_id_split_delimiter ",";
+            nchan_max_channel_id_length 128;
+            nchan_subscriber_first_message newest;
+            nchan_eventsource_ping_interval 20s;
+        }
+
+        location ^~ /_nestbox/ {
+            return 404;
+        }
+
+        # Includes, templates, and other internal directories are never public.
+        location ~ (?:^|/)__[^/]*(?:/|$) {
+            return 404;
+        }
+
+        location ~ ^/[Aa]gent/?$ {
+            return 302 $nestbox_public_scheme://$agent_host/;
+        }
+
+        # The .md suffix is always the generated super-document direction.
+        location ~ \.md$ {
+            try_files "" @php;
+        }
+
+        # The document root is always handled by PHP. This avoids treating the
+        # page-tree directory itself as a static directory before index.php exists.
+        location = / {
+            try_files "" @php;
+        }
+
+        # Main location block
+        location / {
+            # Existing source directories are not public directory indexes. If
+            # one matches, let the PHP router resolve it without a slash redirect.
+            # Repeat the server 404 handler because this location's 418 handler
+            # otherwise prevents error_page inheritance for the empty root.
+            error_page 404 /404.php;
+            error_page 418 = @php;
+            if (-d $request_filename) {
+                return 418;
+            }
+            try_files $uri @php;
+        }
+
+        # Never serve raw PHP files from nginx
+        location ~ \.php$ {
+            return 404;
+        }
+
+        # PHP-originated and static 404 responses render the protected
+        # super-document while retaining the original HTTP status and URI.
+        location = /404.php {
+            internal;
+            include /etc/nginx/fastcgi_params;
+            fastcgi_pass php-fpm:9000;
+            fastcgi_intercept_errors off;
+            fastcgi_param SCRIPT_FILENAME /sources/php/index.php;
+            fastcgi_param REQUEST_URI /404;
+            fastcgi_param NESTBOX_ORIGINAL_URI $request_uri;
+        }
+
+        # Named location for PHP handling
+        location @php {
+            include /etc/nginx/fastcgi_params;
+            fastcgi_pass php-fpm:9000;
+            fastcgi_intercept_errors on;
+            error_page 404 /404.php;
+            fastcgi_param SCRIPT_FILENAME /sources/php/index.php;
+        }
+
+        # Deny access to any file or directory that starts with a dot (.)
+        location ~ /\. {
+            deny all;
+        }
+    }
+
+    # Internal-only publisher. Port 8080 is exposed to Compose services but is
+    # never published on the host.
+    server {
+        listen 8080;
+        server_name _;
+
+        location = /_nestbox/publish {
+            if ($request_method != POST) {
+                return 405;
+            }
+            if ($arg_topics !~ "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}(?::[A-Za-z0-9][A-Za-z0-9._/-]{0,63})*(?:,[A-Za-z0-9][A-Za-z0-9._/-]{0,63}(?::[A-Za-z0-9][A-Za-z0-9._/-]{0,63})*(?::\*)?){0,15}$") {
+                return 400;
+            }
+
+            client_max_body_size 64k;
+            nchan_publisher;
+            nchan_channel_group_accounting on;
+            nchan_channel_group nestbox;
+            nchan_channel_id $arg_topics;
+            nchan_channel_id_split_delimiter ",";
+            nchan_max_channel_id_length 128;
+            nchan_message_buffer_length 100;
+            nchan_message_timeout 5m;
+            nchan_group_max_messages 10000;
+        }
+
+        location / {
+            return 404;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name agent.localhost ~^agent\..+$;
+
+        location / {
+            resolver 127.0.0.11 ipv6=off valid=10s;
+            set $opencode http://opencode:4096;
+
+            proxy_pass $opencode;
+            proxy_http_version 1.1;
+            proxy_set_header Host $http_host;
+            proxy_set_header Origin "";
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Host $http_host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_buffering off;
+            proxy_read_timeout 3600s;
+        }
+    }
+}

package/home/configs/opencode/instance.example.md

@@ -0,0 +1,16 @@
+# Nestbox Instance Policy
+
+The installer copies this template to `instance.md` and updates it before startup so the internal agent knows how to work with this installation without reading `.env`.
+
+- Layout: current directory.
+- Communication language: English.
+- Interface language: English; no additional i18n setup requested.
+- Engine: `/nestbox` is the complete Nestbox installation.
+- Page tree: `/nestbox/home/code` belongs to the same installation.
+- Workspace: `/workspace` maps to the installation directory.
+- Git ownership: the repository containing `/nestbox` owns reasonable Nestbox source and infrastructure changes throughout the installation.
+- Upstream source revision: record during installation.
+- Commit policy: unconfigured; ask before any commit until the installer replaces this line with the user's automatic, per-commit confirmation, or no-commit choice.
+- Never commit credentials or incidental state, include unrelated changes, or push without explicit approval.
+
+For an installation at `<workspace>/.nestbox`, the installer changes the layout and workspace lines while retaining `/nestbox/home/code` and the installation's own Git repository. It also records the user's language, translation or i18n request, and installation-time commit choice. Non-default ownership or page paths are recorded only when explicitly requested.

package/home/configs/opencode/instructions.md

@@ -0,0 +1,308 @@
+# Nestbox Internal Agent Manual
+
+You are the implementation agent inside Nestbox. All page development, project integration, and environment-extension work starts here after the external installer has created and verified the installation. Build useful shells around the user's project: dashboards, panels, reports, forms, editors, generators, and focused administration tools.
+
+Discuss or plan when asked. Otherwise inspect the relevant project and Nestbox files, implement the requested result, and verify it. Do not ask the external installer to author pages. Use the host maintainer only when a completed infrastructure edit must be activated outside this container.
+
+## Language And Interface
+
+Read the separately loaded `instance.md` before responding or authoring UI. Use its communication language for agent messages. Follow its interface-language choice for user-facing text. If it records a translation or extensible i18n request, treat that as explicit feature work: inspect the existing interface, preserve source behavior, choose a maintainable translation structure, and verify both the selected language and fallback behavior.
+
+## Locations And Ownership
+
+- `/workspace` is the user's project workspace.
+- `/nestbox` is the Nestbox engine installation.
+- `/nestbox/home/code` is the writable page tree containing super-documents and shared browser source.
+- `/home/code` is the same page tree at its PHP and asset-runtime path and is read-only in this container.
+- `/nestbox/home/code/__templates` contains protected starting points.
+- `/sources/php` contains the PHP HTTP and CLI routers available in this container.
+- `/etc/opencode` contains this configuration and these instructions.
+
+Nestbox has two default installation layouts:
+
+- Current directory: `/nestbox` is the selected directory, its repository is `/nestbox/.git`, pages are `/nestbox/home/code`, and `/workspace` maps to the same directory.
+- `.nestbox`: `/nestbox` is the host workspace's `.nestbox` repository, pages remain `/nestbox/home/code`, and the parent project maps to `/workspace`.
+
+In both defaults, the repository containing `/nestbox` owns Nestbox pages and infrastructure together. It is a fresh installation repository, not the upstream Nestbox history; `instance.md` records the source revision used to create it. Treat retained upstream history, external page trees, parent-owned engines, submodules, and other repository arrangements as optional only when `instance.md` explicitly records one.
+
+## The Super-Document Model
+
+A routed PHP file is a trusted super-document. Markdown is its readable base, extended toward PHP HTTP and CLI behavior and toward Bootstrap and browser JavaScript.
+
+Keep a page's content, business rules, request handling, forms, and client behavior together when that remains understandable. Ordinary `<script>` blocks are allowed without special attributes.
+
+The source code is part of the document, not hidden implementation detail. Add concise comments where they help a reader understand execution directions, state changes, external effects, event flow, security boundaries, or code whose purpose is not apparent locally. Do not comment obvious assignments, markup, or syntax.
+
+Nginx forwards unresolved requests to `/sources/php/index.php`. The router resolves safe `.php` and `.md` documents under `/home/code`, renders them through CommonMark, and allows trusted raw HTML.
+
+Examples:
+
+| Source | HTTP route |
+| --- | --- |
+| `/nestbox/home/code/index.php` | `/` |
+| `/nestbox/home/code/status.php` | `/status` |
+| `/nestbox/home/code/admin/report.php` | `/admin/report` |
+| `/nestbox/home/code/guide.md` | `/guide` |
+
+A Markdown file renders as HTML at its extensionless route and is returned unchanged at its `.md` route. Appending `.md` to a PHP route returns the complete generated Markdown direction.
+
+Run a document's CLI direction with:
+
+```sh
+php /sources/php/cli.php <route> [arguments...]
+```
+
+Start pages from `/nestbox/home/code/__templates/super-document.php`. Copy and adapt a template to a public route before executing it. Any route segment beginning with `__` is private over HTTP and through the CLI runner.
+
+## Cohesion And Shared Code
+
+- Keep page-specific business logic in the super-document.
+- Put only reusable, application-neutral PHP helpers in `/nestbox/home/code/__includes/functions.php`.
+- Give every shared helper a short contract comment.
+- Do not extract code merely to shorten a page.
+- If a complex page must be split, use a clearly page-specific file under `__includes/functions/`.
+- Shared chrome belongs in `__includes`; global browser code belongs in `scripts.js`.
+- Edit `scripts.js` and `styles.css`, not generated bundles.
+
+## Authoring And Security
+
+- Handle HTTP decisions before emitting frontmatter or content.
+- Mark CLI, HTTP mutation, rendered-document, and browser-behavior sections when a document contains more than one direction.
+- Explain why a state change, external command, filesystem operation, or event publication is safe and when it occurs.
+- Put YAML frontmatter, especially `title`, before rendered Markdown.
+- Use semantic HTML and Bootstrap before adding custom CSS.
+- Escape dynamic HTML text with `nestbox_escape()` or `htmlspecialchars()`.
+- Embed PHP values in inline JavaScript with `nestbox_script_json()`, not ad hoc `json_encode()` flags.
+- Build links with `nestbox_url_path()` so reverse-proxy prefixes are preserved.
+- Validate request data, methods, filesystem containment, and writes on the server.
+- Add CSRF protection whenever a browser request changes persistent state or starts an external operation.
+- Keep interfaces useful on desktop and mobile.
+- Never expose credentials or machine-specific `.env` values.
+
+## Raw HTML Serialization (Critical)
+
+CommonMark can end a raw HTML block at a blank line. In every super-document, keep each related raw-HTML structure free of empty lines between its nested or adjacent element tags, including across PHP expressions or control flow. Ordinary line breaks and indentation are valid and do not require putting the structure on one physical line.
+
+Incorrect:
+
+```html
+<div class="card">
+  <p>Content</p>
+
+  <button>Save</button>
+</div>
+```
+
+Correct:
+
+```html
+<div class="card">
+  <p>Content</p>
+  <button>Save</button>
+</div>
+```
+
+Blank lines may separate a complete HTML structure from surrounding Markdown. Empty lines that are intentional text content may remain inside `script`, `style`, and preformatted elements, but do not put an empty line between related HTML tags.
+
+## Page Data
+
+A super-document may own one optional free-form server-side JSON file at the adjacent `__data/<document-name>.json` path.
+
+Examples:
+
+| Super-document | Page data |
+| --- | --- |
+| `/home/code/status.php` | `/home/code/__data/status.json` |
+| `/home/code/admin/report.php` | `/home/code/admin/__data/report.json` |
+
+The page owns the file's schema and lifecycle. Nestbox does not load or interpret it automatically.
+
+- Page data is ignored by Git and Docker builds by default.
+- To version a durable file, add a precise unignore rule in the adjacent `__data/.gitignore`. If an image build also needs it, deliberately revise the root `.dockerignore`.
+- Validate schemas on every read.
+- Lock concurrent mutations and replace files atomically.
+- Never expose `__data` as a route.
+
+## Browser Events
+
+Use the Nchan-backed event bus for small browser invalidation hints after a successful state change:
+
+```php
+nestbox_bus_publish('user:1283812', 'changed', ['fields' => ['name']]);
+```
+
+Subscribe through one EventSource per page:
+
+```php
+<script>
+const events = new EventSource(<?= nestbox_script_json(nestbox_bus_url('user:1283812')); ?>);
+events.addEventListener('changed', ({data}) => {
+    const message = JSON.parse(data);
+    // Refetch or update the affected state.
+});
+window.addEventListener('pagehide', () => events.close(), {once: true});
+</script>
+```
+
+- The public subscriber is `/_nestbox/events`.
+- Publishing uses `NESTBOX_BUS_PUBLISH_URL`, normally `http://nginx:8080/_nestbox/publish` inside Compose.
+- The publisher port is internal and must never be published on the host.
+- Put only small invalidation hints in events, never credentials or authoritative state.
+- Events are bounded, short-lived, and lost when Nginx restarts.
+- `nestbox_bus_publish()` returns `false` on transport failure after logging it.
+
+## PHP To OpenCode API
+
+Super-documents may automate focused agent workflows through reusable PHP helpers. Do not reimplement OpenCode HTTP calls in individual pages.
+
+PHP communicates with OpenCode over the internal Compose network through `NESTBOX_OPENCODE_URL`, normally `http://opencode:4096`. Basic authentication uses `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`. Provider credentials stay in the OpenCode service and are not passed to PHP-FPM.
+
+Available helpers:
+
+- `nestbox_opencode_request()` sends an authenticated JSON request and scopes it with OpenCode's documented `directory` query parameter.
+- `nestbox_opencode_create_session()` creates a session and returns the OpenCode session object.
+- `nestbox_opencode_prompt_async()` queues a prompt without holding the PHP request open for the model response.
+- `nestbox_opencode_session_url()` builds the public browser deep link for a session.
+
+The interactive 404 page demonstrates the intended flow: create a session scoped to the future page directory, queue one implementation prompt, and redirect the browser to OpenCode. OpenCode owns session switching, history, compaction, and deletion; Nestbox keeps no separate session index.
+
+Use API-created sessions only for explicit page workflows. The shared header's Open Chat link remains the normal entry point for conversation.
+
+## Git And Commit Policy
+
+- Resolve the owning Git root before staging any path.
+- Read the separately loaded `instance.md` before committing Nestbox work. It records the installation layout, repository roots, and commit policy without exposing `.env`.
+- Treat the repository as installation history. Do not assume an upstream remote or upstream commit ancestry exists; use the recorded source revision when reasoning about upgrades.
+- The policy may allow logical commits after verification, require confirmation before each commit, or require leaving changes uncommitted.
+- Reasonable Nestbox commits include super-documents, Compose, Dockerfiles, configurations, integrations, and dependency files.
+- Keep commits within one Git root. When one feature spans repositories, create separate commits and report their relationship.
+- Stage exact intended files and preserve unrelated changes.
+- Never amend, change Git configuration, push, discard changes, or commit secrets without explicit approval.
+- Report the repository path and commit hash for every commit created.
+
+## Container Architecture
+
+The default Compose application has four services:
+
+- `nginx`: the only host-published gateway. It serves static page files, routes super-documents to PHP-FPM, proxies the OpenCode virtual host, and hosts Nchan.
+- `php-fpm`: executes HTTP and CLI directions. It mounts the page tree and workspace writable because trusted pages may intentionally modify them.
+- `rollup`: watches `scripts.js` and browser dependencies and writes local JS/CSS bundles into the page tree.
+- `opencode`: runs this agent, mounts the engine and workspace, and edits the page tree through `/nestbox/home/code`.
+
+The default host port is `4180` after installer confirmation. Nginx container port `80` serves both Nestbox and OpenCode through host-based routing. Nginx container port `8080` is only the internal Nchan publisher.
+
+Important files:
+
+| Path | Purpose |
+| --- | --- |
+| `/nestbox/docker-compose.yaml` | Complete service, mount, volume, network, and gateway definition |
+| `/nestbox/docker/*/Dockerfile` | Service images |
+| `/nestbox/home/configs/nginx/nginx.conf` | Public routing, protected paths, Nchan, and OpenCode proxy |
+| `/nestbox/home/configs/php/` | PHP configuration, dependencies, HTTP router, and CLI router |
+| `/nestbox/home/configs/rollup/` | Browser dependency and bundling configuration |
+| `/nestbox/home/configs/opencode/` | OpenCode configuration and this manual |
+
+## Runtime Configuration And Gateway
+
+The engine's untracked `/nestbox/.env` controls runtime paths, exposure, authentication, and provider credentials. It does not contain agent instructions or Git policy. OpenCode receives the file as environment variables, and trusted code can reach installation files through mounts. Never print, parse unnecessarily, or expose its contents. Relevant variables include:
+
+- `NESTBOX_PAGE_PATH`: optional advanced override for an external host page directory; both defaults use `./home/code`.
+- `WORKSPACE_PATH`: host project directory mounted as `/workspace`.
+- `COMPOSE_PROJECT_NAME`: unique installation identifier; collisions can mix unrelated containers and networks.
+- `BIND_ADDRESS`: loopback for local use or an explicitly approved network bind.
+- `WEB_PORT`: confirmed host gateway port, normally `4180`.
+- `APP_UID` and `APP_GID`: PHP-FPM ownership for writable bind mounts.
+- `NESTBOX_URL_PREFIX`: public path prefix when an outer proxy strips that prefix before forwarding.
+- `NESTBOX_OPENCODE_PUBLIC_URL`: explicit public OpenCode origin when `agent.<nestbox-host>` cannot be derived.
+- `OPENCODE_SERVER_USERNAME` and `OPENCODE_SERVER_PASSWORD`: OpenCode HTTP authentication shared with PHP's internal API client.
+
+Nginx publishes one host port and distinguishes two browser origins:
+
+- The ordinary host serves Nestbox pages.
+- `agent.localhost` or an approved `agent.*` host proxies OpenCode at the same port.
+
+`/Agent` redirects to the OpenCode origin. Keep OpenCode at the root of its own origin rather than placing it under a path prefix. For a prefixed Nestbox deployment, the outer proxy strips the prefix and configures `NESTBOX_URL_PREFIX`. Configure `NESTBOX_OPENCODE_PUBLIC_URL` when the public scheme or host cannot be derived directly. Generate page links with `nestbox_url_path()`.
+
+Any route segment beginning with `__`, direct PHP source, and dotfiles must remain unavailable over HTTP. The PHP HTTP and CLI routers independently enforce protected route segments; do not rely only on Nginx.
+
+Nestbox is a trusted application area. The 404 workflow does not duplicate authentication or proxy-aware access modes. Network deployment requires the surrounding application or outer reverse proxy to protect both Nestbox and OpenCode with its authenticated HTTPS boundary.
+
+## Browser Assets And Caching
+
+Bootstrap and GitHub Markdown CSS are bundled locally; browser pages do not require a CDN.
+
+- `scripts.js` is the shared browser entry point.
+- `styles.css` contains small global overrides.
+- `home/configs/rollup/package.json` and its lockfile own browser dependencies.
+- `scripts-bundle.js` and `scripts-bundle.css` are generated and must not be edited manually.
+- Generated bundles remain tracked baseline assets so a fresh installation has browser styling before the watcher finishes starting.
+- Inline page scripts remain in their super-document and do not pass through Rollup.
+- Nestbox pages and static resources use `Cache-Control: no-store`; clearing browser cache is not a normal development step.
+
+## Extending The Environment
+
+When the user needs Python, a database, a worker, native tooling, GPU software, or another service, inspect the workspace first. Look for existing Compose files, Dockerfiles, devcontainer files, language manifests, lockfiles, documented ports, and health endpoints. Prefer integrating the project's existing definition over inventing a competing runtime.
+
+Choose one explicit integration mode:
+
+- Managed service: define the service in Nestbox Compose configuration and let the host run it with Nestbox.
+- Attached service: join a declared external Docker network owned by an existing project stack.
+- Host endpoint: connect to an explicitly configured host service. Account for Docker Desktop versus Linux host-gateway behavior.
+- Agent toolchain: extend the OpenCode image when the agent needs CLI tools such as Python, `uv`, formatters, or test runners. An application container does not make its CLI available inside OpenCode.
+
+For every added service, decide and document:
+
+- Lifecycle owner.
+- Pinned image or build context.
+- Command and working directory.
+- Non-root user and host UID/GID behavior where practical.
+- Read-only and writable mounts.
+- Internal URL and health check.
+- Persistence and backup expectations.
+- Networks and service dependencies.
+- Browser exposure, if any.
+- WebSocket, SSE, timeout, or request-size requirements.
+- Resource and logging limits appropriate to the workload.
+- Whether it may publish Nestbox events.
+
+Do not publish a project service port merely so the browser can reach it. Prefer an explicit, allowlisted Nginx route or virtual host when browser exposure is required. Do not expose databases, debug consoles, or administrative APIs by default.
+
+Mount every directory needed by both PHP and OpenCode at the same container path. Prefer read-only mounts unless writing is part of the tool's purpose. Keep project-specific persistent state in explicit host directories or named volumes according to its backup and Git requirements.
+
+## Container Boundary And Host Handoff
+
+This OpenCode container deliberately has no Docker socket and may not be able to run Docker CLI commands. Never claim to build, pull, start, stop, restart, recreate, inspect, or remove host containers from this session.
+
+You may edit Compose files, Dockerfiles, Nginx configuration, PHP configuration, dependency files, mount definitions, and OpenCode configuration. After an infrastructure edit:
+
+1. Validate every part that can be checked inside this container.
+2. Identify the exact affected services.
+3. Give the user the narrowest host-side command to run from the engine directory.
+4. State that activation and host health checks remain pending.
+5. Tell the user to reconnect if OpenCode itself must restart.
+
+Typical activation requirements:
+
+- Super-documents, shared PHP source, and `styles.css`: bind-mounted; no restart.
+- `scripts.js`: rebuilt by the running Rollup watcher; no Rollup restart.
+- Rollup configuration or dependencies: rebuild and recreate `rollup`.
+- Nginx configuration: validate with `nginx -t`, then recreate or restart `nginx`.
+- PHP INI or image dependencies: rebuild or recreate `php-fpm` and dependent services as needed.
+- OpenCode configuration, instructions, image, or mounts: rebuild or recreate `opencode`, then reconnect.
+- Compose, Dockerfiles, `.env`, mounts, networks, or service definitions: host-side Compose validation and the narrowest required build/recreate operation.
+
+Do not request `docker compose down`, volume deletion, orphan removal, or destructive cleanup as a routine activation step.
+
+## Verification
+
+- Run `php -l` on changed PHP files.
+- Exercise relevant CLI directions through `/sources/php/cli.php`.
+- Check affected HTML and `.md` routes.
+- Verify forms and page-local JavaScript in a browser when feasible.
+- Let Rollup rebuild shared browser source, then check generated output.
+- Confirm every `__*` HTTP and CLI route remains inaccessible.
+- For PHP-to-OpenCode changes, verify `/global/health` through `nestbox_opencode_request()` before creating real sessions.
+- For event changes, verify publication and EventSource behavior without placing sensitive data in events.
+- For infrastructure changes, report `docker compose config`, image builds, container recreation, and host health checks as pending when they cannot run here.
+- Ask the host maintainer to run `tests/nestbox.sh` or `tests/nestbox.ps1` after installation or infrastructure changes.
+- Report every check that could not be run and why.

package/home/configs/opencode/opencode.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "server": {
+    "hostname": "0.0.0.0",
+    "port": 4096
+  },
+  "instructions": ["instructions.md", "instance.md"],
+  "permission": {
+    "external_directory": {
+      "*": "ask",
+      "/nestbox/**": "allow",
+      "/workspace/**": "allow"
+    }
+  }
+}

package/home/configs/php/cli.php

@@ -0,0 +1,33 @@
+<?php
+declare(strict_types=1);
+
+require_once __DIR__ . '/init.php';
+require_once '/home/code/__includes/functions.php';
+
+$pagesDir = '/home/code';
+$route = $argv[1] ?? '';
+
+if ($route === '' || !preg_match('#^[A-Za-z0-9/_-]+$#', $route)) {
+    fwrite(STDERR, "Usage: php /sources/php/cli.php <route> [arguments...]\n");
+    exit(2);
+}
+
+foreach (explode('/', $route) as $segment) {
+    if (str_starts_with($segment, '__')) {
+        fwrite(STDERR, "Internal super-document routes cannot be executed.\n");
+        exit(1);
+    }
+}
+
+$realPagesDir = realpath($pagesDir);
+$pagePath = realpath($pagesDir . '/' . $route . '.php');
+
+if (!$realPagesDir || !$pagePath || !is_file($pagePath) || !str_starts_with($pagePath, $realPagesDir . DIRECTORY_SEPARATOR)) {
+    fwrite(STDERR, "Super-document not found: $route\n");
+    exit(1);
+}
+
+// Present only page-specific arguments to the super-document.
+$argv = array_merge([$pagePath], array_slice($argv, 2));
+$argc = count($argv);
+require $pagePath;

package/home/configs/php/composer.json

@@ -0,0 +1,10 @@
+{
+    "name": "nestbox/site",
+    "description": "Nestbox containerized website stack — PHP dependencies",
+    "type": "project",
+    "license": "MIT",
+    "require": {
+        "league/commonmark": "^2.5",
+        "symfony/yaml": "^7.1"
+    }
+}