adom-cli

@@ -0,0 +1,242 @@+---+name: containers+description: "Adom Containers: Create, inspect, list, resize, and manage containers and port mappings. Includes lightweight sshd-only containers."+---++# Container Management++Create and manage Adom containers -- SSH-accessible development environments tied to repositories.++## Auto-detection++All repo-scoped commands auto-detect the current repo from `VSCODE_PROXY_URI`. **You do not need to parse the slug or pass owner/repo** -- just omit them:++```bash+# List containers for the CURRENT repo (auto-detected)+adom-cli carbon containers list-for-repo++# Or explicitly target a different repo+adom-cli carbon containers list-for-repo kcknox other-repo+```++## When to use++- User asks "what containers does this repo have?" -> `adom-cli carbon containers list-for-repo`+- User asks "list my containers" or "show all my containers" -> `adom-cli carbon containers list`+- User wants to create, inspect, resize, or list containers+- User needs to expose a port from a container (port mappings)+- User asks about available container images or sizes+- User wants to resize a container -> `adom-cli carbon containers resize`+- User wants a lightweight service container -> create with `default-light` image++## Commands++### List containers for a repo+```bash+adom-cli carbon containers list-for-repo          # current repo+adom-cli carbon containers list-for-repo owner repo  # specific repo+```++### Create a container+```bash+adom-cli carbon containers create --image-id <IMAGE_ID> --repo-id <REPO_ID> --class small+```+- `--image-id` (required): the image to use (see `images` command)+- `--repo-id` (**required**): attach to a repository. The Carbon API allows omitting this, but the CLI refuses because orphan containers are hard to find, easy to forget, and almost never the intent. Association can only be set at creation time and cannot be changed later — get the id right the first time (`adom-cli carbon repos list` to find it).+- **SSH is enabled by default** (v0.4.11+). Pass `--no-ssh` to opt out. A container without SSH cannot be deployed to and cannot be retrofitted today — see adom-cli#3.+- `--ssh` (**deprecated no-op**): kept for script compatibility. SSH is now default-on; passing this flag has no effect.+- `--class`: `small` (1 vCPU, 4GB), `medium` (2 vCPU, 8GB), `large` (4 vCPU, 16GB). Defaults to small.++### Create a lightweight container (sshd-only)++The `default-light` image runs only sshd -- no VS Code, no services. Use it for:+- Dedicated service hosts (HTTP APIs, background workers)+- SSH-accessible compute nodes+- Minimal overhead containers (~7MB RAM idle)++```bash+# List images to find default-light+adom-cli carbon containers images++# Create lightweight container (SSH on by default — just --repo-id required)+adom-cli carbon containers create \+  --image-id 69b43b3e58d13e5ce628cdc5 \+  --class small \+  --repo-id <REPO_ID>+```++When associated with a repo, the SSH username includes the repo name for easy identification:++```json+{+  "slug": "rk6euj7525tq",+  "image_name": "default-light",+  "repository": {"full_name": "john/service-wiki", "...": "..."},+  "ssh_credentials": {+    "command": "ssh [email protected]",+    "hostname": "adom.cloud",+    "port": 22,+    "username": "john-service-wiki-rk6euj7525tq"+  }+}+```++**Important:** Lightweight containers have no VS Code editor or web interface. Access them only via SSH. The image includes node, git, python3, and curl but no IDE.++**Prerequisites:** You need an SSH key registered with your Adom account to connect. See the `ssh-keys` skill for key management commands.++### Connect via SSH after creation++Use the `ssh_credentials.command` from the creation response:++```bash+ssh -o StrictHostKeyChecking=accept-new [email protected]+```++New containers may need 15-30 seconds to provision before SSH is available.++### Get a container by slug+```bash+adom-cli carbon containers get <slug>+```++### Find the current container++The `containers current` endpoint is **buggy -- do not use it**. Instead parse `VSCODE_PROXY_URI`:++```bash+SLUG=$(echo "$VSCODE_PROXY_URI" | sed 's|https://||;s|\.adom\.cloud.*||' | rev | cut -d- -f1 | rev)+adom-cli carbon containers get "$SLUG"+```++### List available images+```bash+adom-cli carbon containers images+```++Two images are available:+- **Default VSCode** (`default-vscode`): Full VS Code environment with IDE, ~4GB RAM+- **Default Light Weight** (`default-light`): sshd only, ~7MB RAM idle++### Add a port mapping+```bash+adom-cli carbon containers port-add <slug> --port 5173 --prefix dev+```++### Permanent / public / shareable URL for a local service++**This is the Adom port service.** Whenever the user asks for a "permanent+url", "public url", "shareable url", "share this with my brother", "expose+this port", "give me a url", etc., the answer is **always** `port-add` — do+NOT go build a GitHub Pages deploy, do NOT suggest Netlify/Cloudflare/Gist,+do NOT convert the app to static HTML. `port-add` turns any TCP port+already listening on the user's container into a permanent public+`*.adom.cloud` subdomain that anyone on the internet can load in a+browser, no auth wall.++The default Coder proxy URL (`https://<user>-<repo>-<hash>.adom.cloud/proxy/<port>/`)+is behind the user's Adom login and can't be shared. The port mapping+created by `port-add` is the opposite: its own subdomain, anonymous, and+persistent across container restarts.++**Flow:**++1. Resolve the container slug (parse `VSCODE_PROXY_URI` — see "Find the+   current container" above).+2. Pick a URL-safe prefix. Let the user choose, or derive it from the+   app/project name (e.g. `dancing-robot` → `--prefix robot`). Keep it+   short (≤10 chars) and lowercase.+3. Run `adom-cli carbon containers port-add <slug> --port <PORT> --prefix <PREFIX>`.+4. The response contains the new `*.adom.cloud` hostname. Return that+   hostname to the user as the permanent URL, with `https://` in front.+5. Remind the user that the port mapping targets whatever is listening+   on that port NOW and in the future — if the server on that port dies+   or restarts on a different port, the URL stops working until the+   service comes back on the same port.++**Example (dancing robot on port 8796):**++```bash+SLUG=$(echo "$VSCODE_PROXY_URI" | sed 's|https://||;s|\.adom\.cloud.*||' | rev | cut -d- -f1 | rev)+adom-cli carbon containers port-add "$SLUG" --port 8796 --prefix robot+# → https://robot-<random>.adom.cloud+```++**Caveats to tell the user:**++- **The server must keep running** on that port. If you stop the node+  process, the URL goes down until you start it again.+- **The container must be awake**. Sleeping/idle containers will return+  502 until the container wakes up. Port mappings survive sleep; the+  process inside them does not.+- **Anyone with the URL can load it.** No auth. Don't use `port-add` to+  expose anything sensitive.++### Remove a port mapping+```bash+adom-cli carbon containers port-remove <slug> <subdomain>+```++### List your containers (paginated)+```bash+adom-cli carbon containers list+adom-cli carbon containers list --page 2 --limit 25+adom-cli carbon containers list --class medium+```+- `--page`: page number (optional)+- `--limit`: results per page, max 100 (optional)+- `--class`: filter by size -- `small`, `medium`, or `large` (optional)++### Resize a container+```bash+adom-cli carbon containers resize <slug> <class>+```+- `<slug>`: container slug+- `<class>`: new size -- `small`, `medium`, or `large`++## Access Control (ACL)++Share a container with other users by adding them to its access control list. The creator always has access; ACL members get read + SSH (subject to repo permissions).++```bash+# See who's on the ACL (does NOT include creator)+adom-cli carbon containers acl list <slug>++# Add a user — accepts username OR 24-char ObjectId+adom-cli carbon containers acl add <slug> <username>+adom-cli carbon containers acl add <slug> <user-id>   # equivalent++# Remove a user (same: username or ObjectId)+adom-cli carbon containers acl remove <slug> <username>+```++The CLI auto-resolves usernames to user IDs via `GET /users/{name}`. If the username doesn't exist, you get a clean `USER_NOT_FOUND` error before anything mutates.++### ⚠️ Critical: session tokens disable permanently on first ACL add++When you add the **first user** to a container's ACL, that container's session token (`/var/run/adom/api-key`) is **permanently disabled** for ALL Carbon and Hydrogen API calls — not just ACL management. This is a **one-way switch**: even removing all members later does not restore the token.++**Implications:**+- Adding a user to a container that's running `adom-cli` workloads will instantly lock that container out of every API.+- The CLI's `acl add` hint explains this, but **the AI should ask the user before adding to any container being actively used for CLI/AI work.**+- Recovery from a locked container requires either (a) setting `ADOM_API_KEY` to a personal key from another container, or (b) creating a fresh container for CLI work, or (c) asking the user to remove members via the repo page on https://carbon.adom.inc.++**Rule of thumb:** only ACL-share containers that are intentionally collaborative spaces. Never share the container the AI is driving.++### Other ACL behaviors++- Only the creator can list/add/remove. ACL members get 403 FORBIDDEN.+- `containers list` returns containers where the user is creator OR on the ACL.+- `containers get` accepts `?bypass_permissions_check=true` to skip the ACL check (for inspecting from outside).+- SSH access for ACL members works as long as the creator still has write access to the underlying repo.++## Known Limitations++- **No container delete command.** Containers created via `adom-cli` cannot currently be deleted through the API or CLI. See [carbon#39](https://github.com/adom-inc/carbon/issues/39).+- **Repo association is creation-time only.** The `--repo-id` flag can only be set when creating a container. It cannot be changed later. See [carbon#37](https://github.com/adom-inc/carbon/issues/37).+- **No default container setting.** When a repo has multiple containers, there's no API to set which one opens by default. See [carbon#38](https://github.com/adom-inc/carbon/issues/38).+- **Legacy containers lack SSH.** Containers created before the SSH jumphost was deployed return "Could not connect to your container". Create a new container with `--ssh` instead.++## Authentication++In Adom containers, no setup is needed -- the CLI auto-reads the token from `/var/run/adom/api-key`. Just run commands directly.

@@ -0,0 +1,149 @@+---+name: orgs-and-memberships+description: "Adom Organizations: Full org management — CRUD, avatars, invitations, members, memberships, permissions, and org repos."+---++# Organizations & Memberships++Manage organizations on the Adom platform. Includes two command groups:+- `adom-cli carbon user orgs` / `user memberships` / `user invitations` — your own org memberships+- `adom-cli carbon orgs *` — full org operations (admin-level)++## When to use++- User asks about their organizations → `carbon user orgs`+- User asks to create, update, or manage a specific org → `carbon orgs *`+- User wants to invite someone, manage members, or change permissions+- User references an ambiguous name → check their orgs first with `carbon user orgs`++## User-level commands++```bash+# List your organizations+adom-cli carbon user orgs++# List all your memberships+adom-cli carbon user memberships++# Get membership for a specific org+adom-cli carbon user membership <org-name>++# List pending invitations+adom-cli carbon user invitations++# Accept/decline an invitation+adom-cli carbon user invitation-respond <org-name> --accept+adom-cli carbon user invitation-respond <org-name> --decline+```++## Org CRUD++```bash+# List organizations (paginated, searchable)+adom-cli carbon orgs list --q "adom" --page 1 --limit 20++# Create an organization+adom-cli carbon orgs create --name my-org --contact-email [email protected] --business-name "My Company"++# Check org name availability+adom-cli carbon orgs check-name my-org++# Get organization details+adom-cli carbon orgs get <org>+```++## Org Profile Updates++The API uses an untagged enum — send one type of update per request.++```bash+# Rename+adom-cli carbon orgs rename <org> --name new-name++# Update public info+adom-cli carbon orgs update-info <org> --display-name "Adom Inc" --description "Our org" --website-url "https://adom.inc" --location "Toronto" --public-email "[email protected]"++# Update contact email+adom-cli carbon orgs set-contact-email <org> --email [email protected]++# Member permissions+adom-cli carbon orgs set-member-perms <org> --allow-public-repos true --allow-private-repos true --allow-forking-private false++# Admin permissions+adom-cli carbon orgs set-admin-perms <org> --allow-visibility-change true --allow-archiving true --allow-destructive false++# Two-factor requirement+adom-cli carbon orgs set-two-factor <org> --required true+```++## Avatar++```bash+# Upload org avatar+adom-cli carbon orgs avatar-upload <org> /path/to/image.png++# Remove org avatar+adom-cli carbon orgs avatar-delete <org>+```++## Invitations++```bash+# List pending invitations+adom-cli carbon orgs invitations list <org>++# List failed invitations+adom-cli carbon orgs invitations failed <org>++# Invite a user+adom-cli carbon orgs invitations create <org> --user kcknox --owner++# Update invitation (change owner status)+adom-cli carbon orgs invitations update <org> <user-id> --owner true++# Cancel invitation+adom-cli carbon orgs invitations delete <org> <user-id>+```++## Members++```bash+# List public members+adom-cli carbon orgs members list <org>++# Check if a user is a member+adom-cli carbon orgs members check <org> <user>+```++## Memberships++```bash+# List all memberships with permissions+adom-cli carbon orgs memberships list <org>++# Get a user's membership+adom-cli carbon orgs memberships get <org> <user>++# Set member visibility+adom-cli carbon orgs memberships set-visibility <org> <user> --public true++# Set member ownership+adom-cli carbon orgs memberships set-owner <org> <user> --owner true++# Remove member from org+adom-cli carbon orgs memberships remove <org> <user>+```++## Org Repos++```bash+# List org repos (searchable)+adom-cli carbon orgs repos list <org> --q "battery" --page 1 --limit 20++# Create repo in org+adom-cli carbon orgs repos create <org> --name new-project --description "A new project" --private+```++## Authentication++In Adom containers, no setup is needed — the CLI auto-reads the token from `/var/run/adom/api-key`. Just run commands directly. See the [setup](../setup/SKILL.md) skill for details.

@@ -0,0 +1,109 @@+---+name: repos+description: "Adom Repositories: Full CRUD, history, tags, forks, contributors, stars, transfer, and workspaces for repos."+---++# Repository Management++Manage repositories on the Adom platform.++## Auto-detection++All repo-scoped commands auto-detect the current repo from `VSCODE_PROXY_URI`. **Omit owner/repo to target the current repo:**++```bash+# These are equivalent when inside the kcknox/gallia container:+adom-cli carbon repos get+adom-cli carbon repos get kcknox gallia+```++## When to use++- User asks to list, create, update, or delete repos+- User asks about repo history, tags, forks, contributors, or stars+- User wants to transfer a repo or manage workspaces+- User asks "what repos do I have" → `carbon user repos`+- User asks about the current repo → `carbon repos get` (no args needed)++## User-level commands++```bash+# List all your repos+adom-cli carbon user repos++# Create a new repo+adom-cli carbon user repo-create my-repo --description "Optional" --private+```++## Repo CRUD++```bash+# List public repos (paginated)+adom-cli carbon repos list --page 1 --limit 20++# Check if a repo name is available+adom-cli carbon repos check-name <owner> <name>++# Get current repo (auto-detected) or a specific repo+adom-cli carbon repos get+adom-cli carbon repos get <owner> <repo>++# Update current repo+adom-cli carbon repos update --name "new-name" --description "new desc" --private true++# Delete a repo+adom-cli carbon repos delete+```++## History++```bash+adom-cli carbon repos history get+adom-cli carbon repos history push --data '{"schematic_items": []}'+adom-cli carbon repos history revert --commit-id 0+```++## Tags++```bash+adom-cli carbon repos tags list+adom-cli carbon repos tags create --name v1.0 --commit-id 0 --description "first release"+adom-cli carbon repos tags get <tag-name>+adom-cli carbon repos tags update <tag-name> --new-name v1.1 --force+adom-cli carbon repos tags update <tag-name> --description "updated"+adom-cli carbon repos tags delete <tag-name>+```++## Forks & Contributors++```bash+adom-cli carbon repos forks+adom-cli carbon repos contributors+```++## Stars++```bash+adom-cli carbon repos stars check+adom-cli carbon repos stars add+adom-cli carbon repos stars remove+adom-cli carbon repos stars list+```++## Transfer++```bash+adom-cli carbon repos transfer <new-owner>+```++## Workspaces++```bash+adom-cli carbon repos workspaces list+adom-cli carbon repos workspaces current+adom-cli carbon repos workspaces set-current --workspace-id <id>+```++## Authentication++In Adom containers, no setup is needed — the CLI auto-reads the token from `/var/run/adom/api-key`. Just run commands directly.

@@ -0,0 +1,115 @@+---+name: ssh-keys+description: "Adom SSH Keys: List, add, get, and delete SSH keys for git access AND container SSH connections."+---++# SSH Key Management++Manage SSH keys for git authentication (git.adom.inc) AND SSH access to all your Adom containers.++## When to use++- User asks to list, add, or remove SSH keys+- User needs to set up git access to Adom repositories+- User wants to generate and register a new SSH key+- User wants to SSH into an Adom container+- User is troubleshooting SSH connection failures ("Permission denied")+- User wants to copy SSH keys to their desktop++## How Adom SSH keys work++When you register a public key with your Adom account, it enables:+1. **Git access** -- clone/push/pull to `git.adom.inc` repositories+2. **Container SSH** -- SSH into any of your containers via the `adom.cloud` gateway++The SSH gateway at `adom.cloud:22` routes connections based on the username (which encodes the container identity, e.g. `[email protected]`).++## Check if keys exist++### Step 1: Check for a local private key+```bash+ls -la ~/.ssh/id_ed25519 2>/dev/null && echo "Private key exists" || echo "No private key found"+```++### Step 2: Check keys registered with Adom+```bash+adom-cli carbon user ssh-keys+```+If this returns `[]`, no keys are registered.++### Step 3: Diagnose mismatches+- **Private key exists locally but none registered on Adom:** Register it with `ssh-key-add` (see below)+- **Keys registered on Adom but no local private key:** Generate a new keypair and register it+- **Both exist but SSH fails:** Check fingerprints match -- `ssh-keygen -lf ~/.ssh/id_ed25519.pub` vs the fingerprint from `ssh-keys`++## Commands++### List all keys+```bash+adom-cli carbon user ssh-keys+```+Returns: id, display_name, fingerprint, base64_public_key, created_at, last_used_at++### Add a key+```bash+adom-cli carbon user ssh-key-add --display-name "My Laptop" "ssh-ed25519 AAAAC3..."+```+The key string is the full public key line (same format as `~/.ssh/id_ed25519.pub`).++### Get a specific key+```bash+adom-cli carbon user ssh-key <id>+```++### Delete a key+```bash+adom-cli carbon user ssh-key-delete <id>+```++## Common workflow: generate and register a new key++```bash+# Generate key (no passphrase for container-to-container SSH)+ssh-keygen -t ed25519 -C "adom-container" -f ~/.ssh/id_ed25519 -N ""++# Register with Adom account+adom-cli carbon user ssh-key-add --display-name "My Container" "$(cat ~/.ssh/id_ed25519.pub)"++# Verify registration+adom-cli carbon user ssh-keys+```++## Auto-detect and fix (all-in-one)++```bash+# Generate key if missing+if [ ! -f ~/.ssh/id_ed25519 ]; then+  ssh-keygen -t ed25519 -C "adom" -f ~/.ssh/id_ed25519 -N ""+fi++# Register if no keys on Adom+KEYS=$(adom-cli carbon user ssh-keys 2>/dev/null)+if [ "$KEYS" = "[]" ]; then+  adom-cli carbon user ssh-key-add --display-name "auto-generated" "$(cat ~/.ssh/id_ed25519.pub)"+fi+```++## Exporting keys for desktop use++To copy your key to another machine (e.g., your laptop):++```bash+# Display the private key (copy to ~/.ssh/id_ed25519 on your desktop)+cat ~/.ssh/id_ed25519++# Display the public key+cat ~/.ssh/id_ed25519.pub+```++On the desktop, set correct permissions:+- **macOS/Linux:** `chmod 600 ~/.ssh/id_ed25519`+- **Windows (PowerShell as Admin):** `icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant:r "$env:USERNAME:(R)"`++## Authentication++In Adom containers, no setup is needed -- the CLI auto-reads the token from `/var/run/adom/api-key`. Just run commands directly. See the [setup](../setup/SKILL.md) skill for details.