feat: replace plugins.yaml with ai-stack.yaml, add install-* commands

- Rename plugins.yaml → ai-stack.yaml; add mcps: section with all
  services (gmail, mcp-atlassian, gdrive, devlake mysql x2)
- Add /ai-stack:install-plugins, install-skills, install-mcps commands
  with interactive picker, status display, and user/project/local scope
- Register ai-stack plugin in marketplace.json so it's self-installable
- README: new "Getting started with Claude Code" section; replace all
  raw claude mcp add blocks with /ai-stack:install-mcps references
- justfile: remove install-* and check-images recipes (now Claude commands)
- compose.yaml: fix ai-beacon description, remove stale local path refs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kpiwko

.claude-plugin/marketplace.json

@@ -1,5 +1,11 @@
 {
   "plugins": [
+    {
+      "name": "ai-stack",
+      "path": "plugins/ai-stack",
+      "description": "Maintenance commands for ai-stack repos: scaffold services, install plugins/skills/MCPs.",
+      "version": "0.1.0"
+    },
     {
       "name": "dev",
       "path": "plugins/dev",

README.md

@@ -6,7 +6,7 @@ Personal AI tooling stack: Podman Compose services for MCP servers, plus Claude
 
 | Service | Port | Description |
 |---|---|---|
-| ai-beacon | 17090 | Knowledge base / prompt library UI |
+| ai-beacon | 17090 | Session manager for multiple Claude sessions |
 | devlake-local-mysql-mcp | 17301 | Read-only MCP proxy for local DevLake MySQL |
 | devlake-prod-mysql-mcp | 17300 | Read-only MCP proxy for remote Konflux RDS |
 | gmail-mcp | 17633 | Gmail MCP server (search, draft, attachments) |
@@ -32,27 +32,31 @@ podman compose up -d gmail-mcp mcp-atlassian
 
 Container images are built by CI and published to `ghcr.io/kpiwko/` — no local build needed.
 
-## Plugins
+## Getting started with Claude Code
 
-Claude Code plugins live in `plugins/`. Install them once inside Claude Code:
+Install the ai-stack plugin once:
 
 ```
-/plugin install dev@kpiwko/ai-stack
-/plugin install track@kpiwko/ai-stack
-/plugin install quarterly@kpiwko/ai-stack
+claude plugin install ai-stack@kpiwko/ai-stack
 ```
 
-Third-party plugins and bare skills are tracked in `plugins.yaml`. See `just install-plugins` and `just install-skills`.
+Then use it inside a Claude session to set up everything else:
+
+```
+/ai-stack:install-plugins   ← install dev, track, quarterly plugins
+/ai-stack:install-skills    ← install bare skills (template-slide-deck, n8n-skills)
+/ai-stack:install-mcps      ← register MCP servers with Claude Code
+```
+
+All three commands are interactive: they show what's available, what's already installed,
+and let you pick scope (user / project / local) before making any changes.
 
 ## Just recipes
 
 ```bash
-just install-plugins   # print /plugin install commands for Claude Code
-just install-skills    # fetch and install bare skills from plugins.yaml (requires: yq, git)
-just check-images      # verify compose.yaml uses no localhost/ images
-just up                # podman compose up -d
-just down              # podman compose down
-just status            # podman compose ps
+just up       # podman compose up -d
+just down     # podman compose down
+just status   # podman compose ps
 ```
 
 ## gmail-mcp
@@ -64,62 +68,42 @@ reused automatically. On first run, authorize via browser:
 open http://localhost:17633/auth   # complete Google Device Authorization
 ```
 
-Register with Claude Code once:
-
-```bash
-claude mcp add --transport http --scope user gmail http://localhost:17633/mcp
-```
+Then register with Claude Code via `/ai-stack:install-mcps`.
 
 ## devlake-local-mysql-mcp
 
-Connects to a DevLake MySQL instance running on the host at port 3306. Start DevLake first:
-
-```bash
-cd ~/devel/work/devlake
-podman compose -f docker-compose-dev.yml up -d mysql
-```
-
-Then start the MCP proxy:
-
-```bash
-podman compose up -d devlake-local-mysql-mcp
-```
-
-## Registering MCP servers with Claude Code
+Connects to a DevLake MySQL instance running on the host at port 3306. Start DevLake's
+MySQL service first, then register this MCP via `/ai-stack:install-mcps`. The command
+reads `$DEVLAKE_MCP_SECRET_KEY` from the environment — make sure `.env` is sourced first.
 
-MySQL MCPs carry secrets and are registered **project-local** (`--scope local`), which writes
-to `.claude/settings.local.json` (gitignored). Run from the project that needs DB access:
+**Optional: connect via shared Podman network instead of host port**
 
-```bash
-source ~/devel/local-ai/.env
+If DevLake runs in Podman Compose with a named network, you can attach this service to
+that network and reach MySQL by container name — no host port exposure needed.
 
-claude mcp add --transport http --scope local devlake-prod-mysql-mcp \
-  http://localhost:17300/mcp \
-  --header "Authorization: Bearer ${KONFLUX_MCP_SECRET_KEY}"
+1. Find DevLake's network name: `podman network ls`
 
-claude mcp add --transport http --scope local devlake-local-mysql-mcp \
-  http://localhost:17301/mcp \
-  --header "Authorization: Bearer ${DEVLAKE_MCP_SECRET_KEY}"
-```
+2. Declare it as external in `compose.yaml`:
+   ```yaml
+   networks:
+     ai-stack:
+       driver: bridge
+     devprod:        # replace with DevLake's actual network name
+       external: true
+   ```
 
-Verify a server is responding before registering:
-
-```bash
-curl -s -X POST http://localhost:17300/mcp \
-  -H "Authorization: Bearer ${KONFLUX_MCP_SECRET_KEY}" \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-```
+3. Add the network to the service and update `MYSQL_HOST` to the MySQL container name:
+   ```yaml
+   devlake-local-mysql-mcp:
+     networks: [ai-stack, devprod]
+     environment:
+       MYSQL_HOST: mysql   # replace with DevLake's MySQL container name
+   ```
 
 ## mcp-atlassian (Jira)
 
-```bash
-podman compose up -d mcp-atlassian
-claude mcp add --transport http --scope user mcp-atlassian http://localhost:17000/mcp
-```
-
-Credentials come from `.env`: `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`.
+Credentials come from `.env`: `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`. Start the
+service then register via `/ai-stack:install-mcps`.
 
 ## gdrive-mcp (Google Drive)
 
@@ -131,11 +115,7 @@ npx @piotr-agier/google-drive-mcp auth
 ```
 
 This writes `credentials.json` and `tokens.json` into `~/.config/google-drive-mcp/`.
-
-```bash
-podman compose up -d gdrive-mcp
-claude mcp add --transport http --scope user gdrive http://localhost:17100/mcp
-```
+Then start the service and register via `/ai-stack:install-mcps`.
 
 ## OpenShell sandboxes
 

ai-stack.yaml

@@ -0,0 +1,83 @@
+# ai-stack configuration
+#
+# plugins  — Claude Code plugins with slash commands and agents
+#            installed via /ai-stack:install-plugins
+#
+# skills   — bare skills installed directly to .claude/skills/
+#            installed via /ai-stack:install-skills
+#
+# mcps     — MCP servers registered with Claude Code
+#            installed via /ai-stack:install-mcps
+
+plugins: []
+
+# Example plugin entry:
+# - name: jira
+#   source: openshift-eng/ai-helpers   # GitHub owner/repo
+#   version: "v1.2.0"                  # pin to a release tag
+
+skills:
+  - name: template-slide-deck
+    source: toddward/claude-skills-playground
+    path: template-slide-deck
+    version: main
+
+  - name: n8n-skills
+    source: czlonkowski/n8n-skills
+    version: main
+
+# Example skill entry:
+# - name: suggest-reviewers
+#   source: openshift-eng/ai-helpers   # GitHub owner/repo
+#   path: plugins/git/skills/suggest-reviewers  # path inside repo (omit for repo root)
+#   version: "v1.2.0"                  # tag, branch, or commit
+# Scope (user/project/local) is chosen interactively via /ai-stack:install-skills
+
+mcps:
+  - name: gmail
+    transport: http
+    url: http://localhost:17633/mcp
+    scope: user                       # default scope, overridable at install time
+
+  - name: mcp-atlassian
+    transport: http
+    url: http://localhost:17000/mcp
+    scope: user
+
+  - name: gdrive
+    transport: http
+    url: http://localhost:17100/mcp
+    scope: user
+
+  - name: devlake-prod-mysql-mcp
+    transport: http
+    url: http://localhost:17300/mcp
+    headers:
+      Authorization: "Bearer $KONFLUX_MCP_SECRET_KEY"
+    scope: local                      # carries secrets — default to local (not committed)
+
+  - name: devlake-local-mysql-mcp
+    transport: http
+    url: http://localhost:17301/mcp
+    headers:
+      Authorization: "Bearer $DEVLAKE_MCP_SECRET_KEY"
+    scope: local
+
+# Example MCP entries:
+#
+# stdio transport (local process):
+# - name: my-mcp
+#   transport: stdio
+#   command: npx
+#   args: ["-y", "@modelcontextprotocol/server-my-mcp"]
+#   env:
+#     API_KEY: $MY_API_KEY          # references shell env var
+#
+# HTTP/SSE transport with auth header:
+# - name: my-mcp
+#   transport: http                 # http | sse
+#   url: http://localhost:8080/mcp
+#   headers:
+#     Authorization: "Bearer $MY_SECRET"   # $VAR expanded from shell env
+#   scope: local                    # user | project | local
+#                                   # scope is a default — overridable at install time

compose.yaml

@@ -12,10 +12,9 @@
 #   podman compose up -d <name>    # start one service
 #
 # Services:
-#   ai-beacon            — AI Beacon knowledge base UI (port 17090)
+#   ai-beacon            — AI Beacon session manager for multiple Claude sessions (port 17090)
 #   devlake-local-mysql-mcp — MySQL MCP proxy for local DevLake DB (port 17301)
-#                             Requires devlake MySQL running separately via
-#                             ~/devel/work/devlake docker-compose-dev.yml (port 3306).
+#                             Requires DevLake MySQL running on host port 3306.
 #   devlake-prod-mysql-mcp  — MySQL MCP proxy for remote Konflux RDS (port 17300)
 #   gmail-mcp            — Gmail MCP server, streamable HTTP transport (port 17633)
 #   mcp-atlassian        — Jira MCP server, streamable HTTP transport (port 17000)
@@ -33,7 +32,7 @@ volumes:
 services:
 
   ##############################################################################
-  # AI Beacon — knowledge base / prompt library UI
+  # AI Beacon — session manager for multiple Claude sessions
   # URL: http://localhost:17090
   ##############################################################################
   ai-beacon:
@@ -54,7 +53,6 @@ services:
   # MCP endpoint: http://localhost:17301/mcp  (streamable HTTP transport)
   #
   # Connects to DevLake MySQL via host.containers.internal:3306.
-  # Start DevLake first: cd ~/devel/work/devlake && podman compose -f docker-compose-dev.yml up -d
   ##############################################################################
   devlake-local-mysql-mcp:
     image: ghcr.io/kpiwko/mcp-mysql:latest

justfile

@@ -1,69 +1,6 @@
 default:
     @just --list
 
-# Print Claude Code /plugin install commands (run them inside Claude Code)
-install-plugins:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    count=$(yq '.plugins | length' plugins.yaml)
-    if [ "$count" -eq 0 ]; then
-        echo "No plugins configured in plugins.yaml"
-        exit 0
-    fi
-    echo "Run these inside Claude Code:"
-    for i in $(seq 0 $((count - 1))); do
-        name=$(yq ".plugins[$i].name" plugins.yaml)
-        source=$(yq ".plugins[$i].source" plugins.yaml)
-        echo "  /plugin install ${name}@${source}"
-    done
-
-# Install bare skills from 3rd party repos (requires: yq, git)
-install-skills:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    count=$(yq '.skills | length' plugins.yaml)
-    if [ "$count" -eq 0 ]; then
-        echo "No skills configured in plugins.yaml"
-        exit 0
-    fi
-    for i in $(seq 0 $((count - 1))); do
-        name=$(yq ".skills[$i].name" plugins.yaml)
-        source=$(yq ".skills[$i].source" plugins.yaml)
-        path=$(yq ".skills[$i].path // \"\"" plugins.yaml)
-        version=$(yq ".skills[$i].version // \"main\"" plugins.yaml)
-        scope=$(yq ".skills[$i].scope // \"project\"" plugins.yaml)
-
-        if [ "$scope" = "global" ]; then
-            target="$HOME/.claude/skills/$name"
-        else
-            target=".claude/skills/$name"
-        fi
-
-        echo "Installing $name → $target"
-        tmpdir=$(mktemp -d)
-        trap "rm -rf $tmpdir" EXIT
-
-        git clone --depth 1 --filter=blob:none --sparse --branch "$version" \
-            "https://github.com/$source" "$tmpdir" 2>/dev/null
-
-        if [ -n "$path" ]; then
-            git -C "$tmpdir" sparse-checkout set "$path" 2>/dev/null
-            mkdir -p "$target"
-            cp -r "$tmpdir/$path/." "$target/"
-        else
-            mkdir -p "$target"
-            cp -r "$tmpdir/." "$target/"
-        fi
-
-        trap - EXIT
-        rm -rf "$tmpdir"
-        echo "  ✓ done"
-    done
-
-# Check compose services all use ghcr.io images (not localhost/)
-check-images:
-    @grep -n 'image: localhost/' compose.yaml && echo "FAIL: localhost/ images found" && exit 1 || echo "OK: all images use remote registry"
-
 # Start all compose services
 up:
     podman compose up -d

plugins.yaml

@@ -10,3 +10,6 @@ automatically when working inside the ai-stack repository.
 | `/ai-stack:add-service <name>` | Scaffold Containerfile, multi-arch CI workflow, and compose.yaml entry |
 | `/ai-stack:add-workflow <name>` | Generate multi-arch Buildah workflow for an existing service |
 | `/ai-stack:check-images` | Verify all compose.yaml services use remote registry images |
+| `/ai-stack:install-plugins [name\|all]` | Install ai-stack and 3rd party plugins (user/project/local scope) |
+| `/ai-stack:install-skills [name\|all]` | Install bare skills from ai-stack.yaml (user/project/local scope) |
+| `/ai-stack:install-mcps [name\|all]` | Register MCP servers from ai-stack.yaml with Claude Code (user/project/local scope) |