@codions/portta 0.1.0 → 0.3.1

package/README.md

@@ -1,53 +1,39 @@
 # Portta
 
-Portta is a development gateway and panel for running many Docker Compose projects on one machine at the same time. Every HTTP service gets a predictable hostname instead of a port to remember, databases stay private, and one panel shows what is running, how to reach it and what changed in its repository.
+Many Docker projects on one host, each at `project-service.<domain>`, with no published ports, private databases, a login per site, and agents of any brand that know all of this when their session starts.
 
 ```text
 $ portta urls
-http://demo-shop-api.localhost             demo-shop            api
-http://demo-shop-web.localhost             demo-shop            web
-http://demo-site-web.localhost             demo-site            web
+https://demo-shop-api.portta.example     demo-shop   api
+https://demo-shop-web.portta.example     demo-shop   web
+https://demo-site-web.portta.example     demo-site   web
 ```
 
 All of those services listen on the same internal port. None of them publishes a port on the host.
 
-![The Portta Overview: host resources, what needs attention, the Projects, the environments using the host and recent commits](https://raw.githubusercontent.com/codions-labs/portta/main/docs/images/auth-disabled-overview.png)
+![The Portta panel: host resources, what needs attention, the Projects and the environments using the host](https://raw.githubusercontent.com/codions-labs/portta/main/docs/images/auth-disabled-overview.png)
 
 ## The problem it solves
 
-Running several projects, branches or agent worktrees side by side on one host breaks down quickly: two stacks want port 3000, nobody remembers which port belongs to what, the machine may have no public address, and checking a change from a phone means exposing something by hand.
+Running several projects, branches or agent worktrees side by side on one server breaks down quickly: two stacks want port 3000, nobody remembers which port is which, a database ends up reachable from the internet, and showing a change to a client means exposing something by hand.
 
 ## What Portta does
 
-- **Names instead of ports.** One Traefik instance owns ports 80 and 443. HTTP services join a shared Docker network and are routed by a hostname derived from their Compose project and service names.
-- **Parallel environments.** Each Compose project name is a namespace, so a branch or a worktree runs next to the main checkout with its own containers, volumes and URLs.
-- **Private datastores.** Databases and caches stay on each project's private network. You reach one through a temporary loopback bridge or opt-in TLS routing, never through a published port.
-- **Reachable from where you are.** `*.localhost` on a workstation, a domain derived from the host address, your own wildcard domain, Tailscale, or a Cloudflare Tunnel that needs no open port.
-- **The work around the code.** The panel groups environments into Projects, shows each repository's branch, commits and instruction files, reads and writes issues live in GitHub or Linear, and shows logs, resources and activity. The CLI and `portta mcp` expose the same model to scripts and coding agents.
-- **Taskflow.** Git worktrees, persistent agent sessions and multi-agent workflow runs, driven from the panel or the CLI.
+- **Names instead of ports.** One Traefik instance owns ports 80 and 443. Every HTTP service is routed by a hostname derived from its Compose project and service names.
+- **Parallel environments.** A Compose project name is a namespace, so a branch or a worktree runs next to the main checkout with its own containers, volumes and URLs.
+- **Private databases.** Datastores stay on each project's private network. You reach one through a temporary loopback bridge, never through a published port.
+- **A decision per site.** On a public host every routed hostname is protected by a login, open to everybody, or closed because nobody decided. Forgetting leaves it closed. Changing it needs no restart.
+- **Access for a client.** A permanent login, or a temporary link that stops working by itself, from the panel or the CLI.
+- **Agents that know the host.** `portta agents install` teaches Claude Code, Codex, OpenCode and Pi, at the start of every session, where they are running and what applies. They do the work; Portta decides where it runs and how it is reached.
+- **A panel that fits in a phone.** What is running, at which URL, whether it is protected, and the controls to change that.
 
 ## What Portta is not
 
-Portta is for development, not deployment. It has no release, rollback or production hosting story, and it should not stand between your users and your application.
-
-It is host infrastructure installed once, not a parent Compose project. It does not move your projects, own their volumes or take part in their lifecycle unless you ask it to start, stop or rebuild one.
+Portta does not run AI, manage git, track issues or deploy releases. It reads where a project's code stands (branch, last commit, what is not committed or pushed) on the host, never asking a remote and never writing to the repository. It gives your tools a place to run projects and a way to reach them. It is host infrastructure installed once, not a parent Compose project, and it never edits your repository.
 
 ## Status
 
-Portta is experimental: a proof of concept built for one small team with fairly
-specific needs, published in that state. It is opinionated about how a project
-is laid out, how environments are named and where work is tracked, and it does
-not try to fit every workflow. Expect rough edges: errors and unexpected
-behaviour can happen in normal use.
-
-We are still deciding whether this approach is useful or only adds another layer
-of bureaucracy and complexity on top of Docker Compose. Several ideas are under
-evaluation.
-
-> [!WARNING]
-> Breaking changes to the CLI, the configuration and the panel are expected if
-> we go ahead with the ideas under evaluation. `v0.x` releases make no
-> compatibility promise.
+`v0.x`: the CLI, the configuration and the panel can change between releases, with no compatibility promise. It is tested locally and in CI. Real DNS and certificate issuance, Cloudflare and Debian 13 have not been exercised by automation; the [deploy guide](https://github.com/codions-labs/portta/blob/main/docs/product/guides/deploy.md) is written so you can verify them on your own host.
 
 ## Requirements
 
@@ -57,78 +43,51 @@ evaluation.
 | Node.js and npm | Node 24 or newer |
 | Operating system | macOS or Linux with a POSIX shell |
 
-Optional: Git (repository metadata and Taskflow), [`gh`](https://cli.github.com) signed in (GitHub issues), `sqlite3` (`portta db shell` and backups), [`just`](https://github.com/casey/just) (checkout shortcuts).
-
-| Verified environment | Evidence |
-|---|---|
-| macOS 15+ arm64 with OrbStack | Full suite run during development |
-| Ubuntu 24.04 amd64 with Docker Engine | Integration in pull-request CI; full end-to-end run on release tags |
-
-Other platforms may work but are not claimed as verified. See the [compatibility reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/compatibility.md).
+Optional: `sqlite3` (`portta db shell` and backups). See the [compatibility reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/compatibility.md).
 
 ## Install
 
-Portta is an npm package. With Node 24 and Docker present, nothing else is needed:
-
 ```bash
 npm install -g @codions/portta
 portta setup
 ```
 
-`setup` checks Node, Docker and Compose, asks for one confirmation, then installs the runtime into `~/portta`, prepares `.env`, pulls the pinned images and starts the gateway. Running it again updates the installation. `portta setup --dry-run` reports what it would do without touching the host.
-
-See [Install Portta](https://github.com/codions-labs/portta/blob/main/docs/product/getting-started/install.md).
-
-## Start
-
-The gateway is running after `setup`. The panel is off until you start it:
-
-```bash
-portta status           # the gateway and what it routes
-portta web up           # the panel on http://127.0.0.1:8081, no sign-in on loopback
-portta doctor           # read-only diagnostics when something is off
-```
-
-## Use
+`setup` checks Node, Docker and Compose, asks for one confirmation, installs the runtime into `~/portta`, pulls the pinned images and starts the gateway. `portta setup --dry-run` reports what it would do. To run the installer once without installing the command, use `npx @codions/portta setup`; for daily use install the command globally. See [Install Portta](https://github.com/codions-labs/portta/blob/main/docs/product/getting-started/install.md).
 
-Add a Compose project you already have. Portta writes its overlay under its own installation state, never inside your repository:
+## Use it in three commands
 
 ```bash
-portta envs analyze /path/to/project      # what adoption needs; writes nothing
-portta adopt /path/to/project             # record the runtime plan
-portta runtime up /path/to/project        # start it through the gateway
-portta urls                               # the routed hostnames
+portta adopt /path/to/project        # plan the runtime; asks who may open each site on a public host
+portta runtime up /path/to/project   # start it behind the gateway
+portta urls                          # the routed hostnames
 ```
 
-Open the panel to see the environment, its services, logs and resources, and to group repositories into a Project. Follow [Configure your first environment](https://github.com/codions-labs/portta/blob/main/docs/product/getting-started/first-environment.md) and [Add your first project](https://github.com/codions-labs/portta/blob/main/docs/product/getting-started/first-project.md).
+On a public host, `adopt` stops until you decide for each routed service: `--protect web` (a generated login, shown once) or `--public api`. Your Compose file is never edited. See [Add your first project](https://github.com/codions-labs/portta/blob/main/docs/product/getting-started/first-project.md).
 
-| Command | What it does |
-|---|---|
-| `portta up` / `portta down` | Start or stop the gateway. Projects keep running. |
-| `portta envs list` / `portta envs show <name>` | Running environments, their services and URLs. |
-| `portta access open --project <p> --service <s>` | A temporary loopback bridge to a private service, such as a database. |
-| `portta web up --expose local\|tailscale\|vpn\|public\|domain` | How the panel is reached. `public` and `domain` require accounts. |
-| `portta config set panel.auth required` | Turn on accounts, roles, Project membership and API tokens. |
-| `portta projects list` / `portta issues list` | Projects in the panel, and the issues of a Project. |
-| `portta host serve --detach` | The host daemon for issues and Taskflow. |
-| `portta mcp` | Serve the Portta tools to a coding agent over stdio. |
-| `portta backup` / `portta update` | Back up the installation, or pull the pinned images and recreate. |
-
-Every command accepts `--json`. The complete list is in the [CLI reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/cli.md).
+## A public host
 
-## Authentication
+For a server on the internet, with every project at `project-service.example.com`:
 
-By default the panel signs nobody in: on loopback, Tailscale or a VPN every request is the local operator. Set `panel.auth` to `required` for accounts with four roles, Project membership, sessions, personal API tokens and an audit log. Public or domain exposure refuses to start without it. See [Configure authentication](https://github.com/codions-labs/portta/blob/main/docs/product/guides/authentication.md).
+1. Create two DNS-only records pointing at the server: `A example.com` and `A *.example.com`. The wildcard does not cover the domain itself, which is where the panel lives.
+2. Create a Cloudflare API token with **Zone, DNS, Edit** on that zone, used to issue one wildcard certificate.
+3. On the server, `npm install -g @codions/portta && portta setup`.
+4. `portta public init --domain example.com --email you@example.com --cloudflare-token-stdin --yes < token-file` writes the public profile, the domain and the token to `~/portta/.env`; then `portta up remote-public`.
+5. `portta dns check && portta doctor`, then open `https://example.com` and create the owner.
 
-## Agent skills
+The [deploy guide](https://github.com/codions-labs/portta/blob/main/docs/product/guides/deploy.md) has each step with the exact records and values, and [Run a public host](https://github.com/codions-labs/portta/blob/main/docs/product/guides/public-host.md) explains the per-site decisions.
 
-Portta publishes its working method as agent skills, so Claude Code, Codex, OpenCode, Cursor and other agents follow the same rules you do:
+## Agents
 
 ```bash
-npx skills add codions-labs/portta -g
+portta agents install     # instructions, a session hook and three skills, for the agents on this machine
+portta agent context      # what an agent sees at the start of a session
 ```
 
-The skills cover branches and worktrees (`portta-method`), commits, pull requests, issues, resolving an issue end to end, authoring workflows, and adopting a Compose project through the CLI (`portta-adopt-compose`). See [the working agreement](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/working-agreement.md).
+The skills (`portta-host-context`, `portta-adopt-compose`, `portta-dockerize`) are also published for `npx skills add codions-labs/portta -g`.
+
+## Security
+
+Nothing is exposed by default: the panel listens on loopback until you say otherwise, datastores stay private, Docker access goes through filtered socket proxies, and on a public host an undecided hostname is closed. Read the [threat model](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/security.md).
 
 ## Develop Portta
 
@@ -138,22 +97,16 @@ cd portta
 just dev               # or: ./bin/portta dev
 ```
 
-This builds the local images, starts the gateway and the panel with hot reloading, and links this checkout's `portta` into `~/.local/bin`. `just dev --demo` also starts the demonstration projects. See [Develop Portta](https://github.com/codions-labs/portta/blob/main/docs/development/development-setup.md) and [Testing](https://github.com/codions-labs/portta/blob/main/docs/development/testing.md).
+See [Develop Portta](https://github.com/codions-labs/portta/blob/main/docs/development/development-setup.md) and [Testing](https://github.com/codions-labs/portta/blob/main/docs/development/testing.md).
 
 ## Documentation
 
 - [Documentation index](https://github.com/codions-labs/portta/blob/main/docs/README.md), also served by the panel at `/docs` and by `portta docs`
-- [Portta architecture](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/architecture.md), [Networking](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/networking.md) and [Security](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/security.md)
-- [Choose remote access](https://github.com/codions-labs/portta/blob/main/docs/product/guides/remote-development.md): Tailscale, Cloudflare Tunnel or a public host
-- [Configuration reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/configuration.md), [CLI reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/cli.md) and [MCP reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/mcp.md)
-- [Taskflow](https://github.com/codions-labs/portta/blob/main/docs/modules/taskflow/README.md)
+- [Architecture](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/architecture.md), [Networking](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/networking.md), [Security](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/security.md)
+- [Configuration reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/configuration.md) and [CLI reference](https://github.com/codions-labs/portta/blob/main/docs/product/reference/cli.md)
 - [Architecture decisions](https://github.com/codions-labs/portta/blob/main/docs/development/adr/README.md)
 - [Changelog](https://github.com/codions-labs/portta/blob/main/CHANGELOG.md)
 
-## Security
-
-Nothing is exposed by default: the panel is off until you start it and then listens on loopback, datastores stay private, Docker access goes through filtered socket proxies, and public or VPN modes require explicit configuration. Read the [threat model](https://github.com/codions-labs/portta/blob/main/docs/product/concepts/security.md).
-
 ## License
 
 MIT. See [LICENSE](https://github.com/codions-labs/portta/blob/main/LICENSE).

package/dist/assets/agents/hook.sh.tmpl

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Managed by Portta: `portta agents install` writes this file and
+# `portta agents uninstall` removes it. Do not edit.
+# Prints the host context for an agent session. Exits silently when Portta is
+# absent, and never fails the agent session.
+PORTTA_NODE_PATH=__PORTTA_NODE_PATH__
+PORTTA_CLI_PATH=__PORTTA_CLI_PATH__
+
+[ -x "$PORTTA_NODE_PATH" ] && [ -r "$PORTTA_CLI_PATH" ] || exit 0
+
+# macOS has no `timeout` without coreutils: use gtimeout when there is one,
+# and otherwise run without a limit, since the command bounds its own probes.
+run=()
+if command -v timeout >/dev/null 2>&1; then
+  run=(timeout 5)
+elif command -v gtimeout >/dev/null 2>&1; then
+  run=(gtimeout 5)
+fi
+
+"${run[@]}" "$PORTTA_NODE_PATH" "$PORTTA_CLI_PATH" agent context --format hook 2>/dev/null || true
+exit 0

package/dist/assets/agents/instruction.md

@@ -0,0 +1,8 @@
+## Portta host
+
+This machine may run Portta, which routes every Docker project at `<project>-<service>.<domain>`.
+At the start of a session, run `portta agent context` unless its output is already in your context.
+
+Never: publish a host port, run `docker * prune`, stop or remove what you did not create, take the gateway down, or reuse another environment's volume or namespace.
+Always: report URLs from `portta urls`, and follow the `portta-host-context` skill when starting or exposing containers.
+If the command is missing, this is not a Portta host and none of this applies.

package/dist/assets/agents/portta-context.ts.tmpl

@@ -0,0 +1,24 @@
+// Managed by Portta: `portta agents install` writes this file and `portta agents uninstall` removes it. Do not edit.
+// Adds the host context to the first turn of each session.
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+const HOOK = __PORTTA_HOOK_PATH__
+
+export default function (pi: ExtensionAPI) {
+  let injected = false
+  pi.on('session_start', () => {
+    injected = false
+  })
+  pi.on('before_agent_start', async (event, ctx) => {
+    if (injected || event.messageType === 'custom') return
+    injected = true
+    try {
+      const result = await pi.exec('bash', [HOOK], { timeout: 8000, cwd: ctx.cwd })
+      const content = result.stdout.trim()
+      if (result.code !== 0 || !content) return
+      return { message: { customType: 'portta-context', content, display: false } }
+    } catch {
+      // The context is a courtesy: a failing hook never blocks the session.
+    }
+  })
+}

package/dist/assets/skills/portta-adopt-compose/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: portta-adopt-compose
+description: Adopt an existing Docker Compose project into a Portta gateway using only the CLI's closed verbs (preflight, analyze, dry-run, decide, adopt, start, report). Use when the Portta preflight reports needs-adoption or non-compliant, or when asked to put a Compose project behind Portta, give it a routed hostname, run it in parallel with others on one host, or decide who may open it on a public host.
+license: MIT
+compatibility: Requires the portta CLI with a running gateway (portta status), Docker Compose 2.24.4 or newer, and read access to the project directory. Never requires the Docker socket.
+metadata:
+  author: codions-labs
+  version: "1"
+---
+
+# Adopt a Compose project with Portta
+
+Adoption puts an existing Compose project behind the Portta gateway: its HTTP
+service gets a hostname, its databases stay private, and it runs next to
+other projects with its own namespace. Portta records everything it decides
+outside the project: the Runtime Plan and the generated overlay live in the
+installation's state, so the project's own files never change.
+
+You drive that with these verbs, in this order, and nothing else:
+
+```
+portta agent context
+portta envs analyze <path> --json
+portta adopt <path> --dry-run --json
+portta adopt <path> [decisions]
+portta runtime up <path>
+portta runtime status <path>
+```
+
+Every `--json` output is `{ "schema", "version", "data" }`; read `data`.
+
+## What you never do
+
+- Edit the project's `compose.yaml`, `Dockerfile`, `.env` or Git history.
+- Write Traefik labels, networks, `docker run` arguments or an overlay by
+  hand. `portta adopt` generates the overlay; a project that wants its own is
+  [manual mode](https://github.com/codions-labs/portta/blob/main/docs/product/guides/adopting-projects.md#manual-mode),
+  which is the person's choice, not yours.
+- Mount or request the Docker socket. Portta reaches Docker through its own
+  filtered proxies.
+- Resolve a decision Portta returned as `pending` on your own. Each one exists
+  because inference would be a guess about the person's project.
+- Create a second Runtime Plan for a project that has one. `runtime up`
+  reuses the recorded plan; a stale plan is regenerated by Portta, not by you.
+
+## The flow
+
+### 0. Start from the preflight
+
+```
+portta agent context --json
+```
+
+It is read-only and finishes in under a second. Adopt only when
+`data.project.scope` is `needs-adoption` (a Compose file and no Runtime Plan)
+or `non-compliant` (read `data.project.violations` to see why). For any other
+scope, do not adopt: `compliant` needs only `portta runtime up`, and
+`out-of-scope`, `excluded`, `no-portta` and `needs-dockerizing` are not this
+skill's job (the last one is `portta-dockerize`). The host rules are in the
+`portta-host-context` skill.
+
+### 1. Read the project
+
+Read the project's instruction files first (`AGENTS.md`, `CLAUDE.md`, a
+`README`). They may say which service is the HTTP surface, which port it
+listens on, or that the project must stay on plain Compose.
+
+### 2. Analyze
+
+```
+portta envs analyze <path> --json
+```
+
+Read-only. `data` names the Compose file it found, the services and what
+they look like, the published host ports and who already holds them, fixed
+container names, published datastores, and whether the namespace is already
+in use by another checkout. When the Compose file is not `compose.yaml` in
+that directory, pass `--file <path>`.
+
+If there is no Compose file, stop: there is nothing to adopt. Say so and
+name the directory you looked in.
+
+### 3. Dry run
+
+```
+portta adopt <path> --dry-run --json
+```
+
+Nothing is written. `data.outcome` is one of:
+
+| Outcome | Meaning | What you do |
+|---|---|---|
+| `isolated` | Portta can run it in its own namespace with a generated overlay | continue to step 5 |
+| `not_supported` | one or more decisions are pending, or something cannot be adopted | step 4 |
+| `manual` | the project owns its integration (`--manual` was recorded) | report; `runtime up` operates the project's own files |
+
+`data.pending[]` lists every unresolved choice with `code`, `service`,
+`detail` and the exact `option` that resolves it. `data.findings[]` lists
+what Portta noticed and will not change (bind mounts, privileged settings).
+`data.services[]` says which service is routed and on which container port.
+
+### 4. Explain the pending decisions, then ask
+
+Explain only what `pending` returned, in the project's terms, one decision at
+a time. Do not add decisions Portta did not raise. Each code maps to one
+question and one option:
+
+| `code` | The question for the person | The option |
+|---|---|---|
+| `ambiguous_port` | which port is the HTTP surface of this service, or should it stay private? | `--service <name>:<port>` |
+| `container_name` | may the fixed `container_name` be reset for this service, so a second environment can run? | `--remove-container-name <name>` |
+| `shared_network` | is sharing this external or fixed network between environments intentional? | `--allow-shared-networks` |
+| `shared_volume` | is sharing this external or fixed volume between environments intentional? | `--allow-shared-volumes` |
+| `public_exposure` | on a public host, who may open this service: only someone with a generated credential, or everybody? | `--protect <service>` or `--public <service>` |
+
+`public_exposure` appears only on a host whose profile is `remote-public`,
+where every routed hostname is closed until somebody decides. It is the
+person's decision and never yours:
+
+- `--protect <service>` asks for a credential to open the service. Portta
+  generates the password. It is shown **once**, in the output of `portta adopt`,
+  and only its hash is kept. Give it to the person in your answer, in the
+  words "shown once", and never write it to a file, a commit, the project's
+  `.env` or a log.
+- `--public <service>` lets everybody open the service, with no login. Ask
+  twice if the service holds anything private.
+- Both options repeat, one per service, and cannot be combined for the same
+  service. Neither exists on a host that is not public.
+- A temporary share link is not an adoption option. It is created in the
+  panel, by the person. Do not try to create one from the CLI.
+
+Two facts help the person decide, and you may state them: a project with no
+HTTP service is still adopted, as a private environment; a multi-port service
+stays private until one port is named.
+
+A finding Portta reports as unsupported, such as `network_mode` on a routed
+service, has no option: report it and stop. The person changes the project or
+keeps it on plain Compose. Do not work around it.
+
+Wait for the answers. Then run the dry run again with the chosen options and
+confirm the outcome is `isolated` before adopting.
+
+### 5. Adopt and start
+
+```
+portta adopt <path> [the options the person chose]
+portta runtime up <path>
+portta runtime status <path>
+portta urls
+```
+
+`adopt` records the plan; `runtime up` validates and starts it; `urls` lists
+the routed hostnames. On a public host `runtime up` creates the containers,
+checks their routing and only then starts them, and it takes a project down
+that carries Traefik routing of its own. Pass the same options to `adopt` that made the dry run
+`isolated`. Never pass an option the person did not choose, and that includes
+`--protect` and `--public`.
+
+### 6. Report
+
+Say, in this order:
+
+1. the outcome and the Compose project name Portta derived;
+2. which service is routed and its URL, and which services stay private;
+3. every decision taken, in the person's words, and every finding left alone;
+4. on a public host, which services are protected and which are open, and the
+   generated credential for each protected one, once, with the reminder that it
+   cannot be shown again (a new one is made by rotating it in the panel);
+5. how to stop and how to recover:
+
+```
+portta runtime status <path>     # what is running
+portta runtime logs <path>       # every service, interleaved
+portta runtime config <path>     # the exact Compose input set Portta uses
+portta runtime down <path>       # stop; the project keeps its data
+```
+
+The project still runs on plain `docker compose` without Portta: adoption
+adds an overlay outside the repository and removes nothing from it.
+
+## Common situations
+
+| Situation | What `analyze` or the dry run shows | What you do |
+|---|---|---|
+| No Compose file | `analyze` fails naming the directory | stop; nothing to adopt |
+| Compose older than 2.24.4 | `adopt` refuses with the required version | report; the person upgrades Compose |
+| Fixed `container_name` | `pending` with `container_name` | ask; `--remove-container-name` only with a yes |
+| External or fixed network / volume | `pending` with `shared_network` / `shared_volume` | ask; the option only when sharing is intentional |
+| Service exposing several ports | `pending` with `ambiguous_port` | ask which port, or keep it private |
+| No HTTP service at all | `isolated`, no routed service | adopt; say the environment is private |
+| `network_mode` on a routed service | unsupported finding | report and stop |
+| Namespace already used by another checkout | `analyze` says so | report; `--project <name>` only if the person names one |
+| Public host, service with no decision | `pending` with `public_exposure` | ask who may open it; `--protect` or `--public` only with an answer |
+| The project brings its own Traefik labels on a public host | `adopt` refuses and names the labels | report; the person removes them, you do not |
+| The project wants its own overlay | the person says so | `--manual`; see the guide's manual mode |
+
+## After adoption
+
+Once the environment runs, the project can be placed in a Project in the
+panel. From inside the directory:
+
+```
+portta projects resolve --json
+```
+
+`resolve` says which Project the directory belongs to, or that none does. It
+is read-only.
+
+## Skill and CLI
+
+The CLI is the contract: every rule above is enforced by `portta adopt`, not
+by this text. This skill only orders the verbs and says what to ask.
+Adoption is a CLI action, because it reads the project directory on the
+host.
+
+Install this skill with `portta agents install`, which also installs the
+preflight hook, or with `npx skills add codions-labs/portta --skill
+portta-adopt-compose -g`. The full contract, the compatibility rules and the
+troubleshooting live in
+[Add an existing project](https://github.com/codions-labs/portta/blob/main/docs/product/guides/adopting-projects.md).

package/dist/assets/skills/portta-dockerize/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: portta-dockerize
+description: Creates a minimal Compose file and Dockerfile for a web project that has none, so it can run behind a Portta gateway with no published ports. Use when the Portta preflight reports needs-dockerizing, or when asked to containerize an app on a Portta host so it gets a routed URL. Always asks for approval before writing files, then hands over to portta-adopt-compose.
+license: MIT
+compatibility: Requires the portta CLI on a Portta host and read access to the project directory. Writes files only after the person approves.
+metadata:
+  author: codions-labs
+  version: "1"
+---
+
+# Dockerize a project for Portta
+
+A project with no Compose file cannot be adopted. This skill writes the
+smallest Compose file and Dockerfile that Portta can route, and then stops so
+the person decides. It never publishes a port and never starts anything.
+
+Start from the preflight (`portta agent context`). Use this skill when
+`data.project.scope` is `needs-dockerizing`. For any other scope, do not
+containerize anything.
+
+## What you never do
+
+- Write a `ports:` entry. Not for the web service, and above all not for a
+  database or a cache. The gateway reaches the service on the shared network.
+- Write Traefik labels, a `portta` network, `container_name` or an overlay.
+  `portta adopt` generates all of that outside the project.
+- Mount the Docker socket.
+- Write or edit a file before the person approved the plan below.
+- Reuse another environment's volume or give a volume a fixed `name:`.
+
+## The flow
+
+### 1. Read the project
+
+Read `AGENTS.md`, `CLAUDE.md`, the `README` and the manifest (`package.json`,
+`composer.json`, `Gemfile`, `pyproject.toml`, `go.mod`). Find the command that
+starts the web server, the port it listens on, the runtime version, and what it
+needs next to it: a database, a cache, a queue.
+
+If you cannot tell which process serves HTTP, ask. Do not guess.
+
+### 2. Propose, in words, before writing
+
+Show the person what you would create, as a short list:
+
+- the files: `compose.yaml` and `Dockerfile` (and `.dockerignore` if the project
+  has none);
+- the services, which one serves HTTP and on which container port;
+- the datastores, and that they stay on the private network with no port;
+- anything you could not infer.
+
+Ask for approval. Wait for the answer. A "no" ends the skill.
+
+### 3. Write the files
+
+Only what was approved. The rules:
+
+- **No `ports:` anywhere.** Use `expose:` only when it documents the port.
+- **Listen on `0.0.0.0`**, not `127.0.0.1` or `localhost`, or the gateway cannot
+  reach the service. Set it through the framework's host option or an
+  environment variable in the start command, for example `--host 0.0.0.0`.
+- **Name the web service plainly** (`web`, `app` or `api`), so Portta recognises
+  it as the HTTP surface.
+- **Databases and caches live only on the Compose network**, with a named
+  volume for their data and no `ports:`. Reach them with
+  `docker compose exec` or `portta db psql`, never by publishing.
+- **Read credentials from the environment**, with a `.env.example` for the
+  person to copy. Never write a real secret into a file.
+- **Keep the Dockerfile small**: a pinned base image tag, dependencies before
+  source for layer reuse, a non-root user when the runtime allows it, and the
+  start command in `CMD`.
+
+A minimal shape, adapted to the project:
+
+```yaml
+services:
+  web:
+    build: .
+    environment:
+      DATABASE_URL: postgres://app:${DB_PASSWORD}@postgres:5432/app
+    depends_on:
+      - postgres
+  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: app
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+volumes:
+  pgdata:
+```
+
+[templates/overlays](https://github.com/codions-labs/portta/tree/main/templates/overlays)
+in the source repository of Portta shows how the stacks Portta knows are wired. Use it as
+a reference for service names and ports, not as something to copy labels from.
+
+### 4. Check, then hand over
+
+```
+docker compose config --quiet
+portta envs analyze . --json
+```
+
+`config --quiet` proves the file is valid. `analyze` is read-only and must show
+no published port. If it does, remove the entry and run it again.
+
+Then stop writing and follow the `portta-adopt-compose` skill from its
+dry-run step: `portta adopt . --dry-run --json`. Do not run `docker compose up`
+yourself: it skips the namespace and the overlay Portta generates.
+
+### 5. Report
+
+Say what you created, which service is the HTTP surface, that no port is
+published, and that the next step is adoption, which needs the person's
+decisions.