@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/cron/suggestions.py

@@ -0,0 +1,257 @@
+"""Suggested cron jobs — proposed automations the user accepts with one tap.
+
+A *suggestion* is a ready-to-run cron job spec that Hermes surfaces to the
+user, who accepts it (creates the real cron job) or dismisses it (latched so
+it is never re-offered). This is the single surface every automation proposal
+flows through, regardless of where it came from:
+
+  * ``catalog``  — a curated starter automation (daily briefing, important-mail
+                   monitor, weekly digest, ...).
+  * ``blueprint``   — the user installed a skill that carries a ``blueprint:`` block
+                   (see ``tools/blueprints.py``); installing it registers a
+                   suggestion instead of auto-scheduling.
+  * ``usage``    — the background self-improvement review noticed a recurring
+                   ask that a scheduled job would serve.
+  * ``integration`` — the user connected an account (Gmail, GitHub, ...) and
+                   the obvious automations for that surface are offered.
+
+Accepting a suggestion just calls the existing ``cron.jobs.create_job`` with
+the stored ``job_spec`` — there is NO second job engine. Suggestions never
+auto-create jobs; acceptance is always explicit (consent-first). Dismissed
+suggestions latch by a stable ``dedup_key`` so the same proposal is not
+re-offered after the user says no.
+
+Storage mirrors ``cron/jobs.py``: ``~/.hermes/cron/suggestions.json``, atomic
+writes, an in-process lock, and 0600 perms.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import threading
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from hermes_constants import get_hermes_home
+from hermes_time import now as _hermes_now
+from utils import atomic_replace
+
+logger = logging.getLogger(__name__)
+
+CRON_DIR = get_hermes_home().resolve() / "cron"
+SUGGESTIONS_FILE = CRON_DIR / "suggestions.json"
+
+# In-process lock protecting load->modify->save cycles (the background review
+# fork and the main agent can both write).
+_suggestions_lock = threading.Lock()
+
+# Cap pending suggestions so the list never becomes a nag wall. When full,
+# new suggestions are dropped (the user should clear the backlog first).
+MAX_PENDING = 5
+
+VALID_SOURCES = frozenset({"catalog", "blueprint", "usage", "integration"})
+_STATUS_PENDING = "pending"
+_STATUS_ACCEPTED = "accepted"
+_STATUS_DISMISSED = "dismissed"
+
+
+def _secure_file(path: Path) -> None:
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _ensure_dir() -> None:
+    CRON_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _load_raw() -> Dict[str, Any]:
+    if not SUGGESTIONS_FILE.exists():
+        return {"suggestions": []}
+    try:
+        with open(SUGGESTIONS_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("suggestions.json unreadable (%s); starting empty", e)
+        return {"suggestions": []}
+    if isinstance(data, dict) and isinstance(data.get("suggestions"), list):
+        return data
+    if isinstance(data, list):
+        return {"suggestions": data}
+    logger.warning("suggestions.json malformed; starting empty")
+    return {"suggestions": []}
+
+
+def _save_raw(suggestions: List[Dict[str, Any]]) -> None:
+    _ensure_dir()
+    fd, tmp_path = tempfile.mkstemp(dir=str(SUGGESTIONS_FILE.parent), suffix=".tmp", prefix=".sugg_")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(
+                {"suggestions": suggestions, "updated_at": _hermes_now().isoformat()},
+                f,
+                indent=2,
+            )
+            f.flush()
+            os.fsync(f.fileno())
+        atomic_replace(tmp_path, SUGGESTIONS_FILE)
+        _secure_file(SUGGESTIONS_FILE)
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def load_suggestions() -> List[Dict[str, Any]]:
+    """Return all suggestion records (any status)."""
+    return _load_raw().get("suggestions", [])
+
+
+def list_pending() -> List[Dict[str, Any]]:
+    """Return pending suggestions in creation order (oldest first)."""
+    return [s for s in load_suggestions() if s.get("status") == _STATUS_PENDING]
+
+
+def add_suggestion(
+    *,
+    title: str,
+    description: str,
+    source: str,
+    job_spec: Dict[str, Any],
+    dedup_key: str,
+) -> Optional[Dict[str, Any]]:
+    """Register a pending suggestion. Returns the record, or None if skipped.
+
+    Skipped when: the source is unknown, the same ``dedup_key`` was already
+    dismissed or accepted (never re-offer), an identical pending suggestion
+    exists, or the pending list is full (``MAX_PENDING``).
+
+    ``job_spec`` is a dict of kwargs for ``cron.jobs.create_job`` — accepting
+    the suggestion passes it straight through, so there is no second schema to
+    keep in sync.
+    """
+    if source not in VALID_SOURCES:
+        raise ValueError(f"unknown suggestion source: {source!r}")
+    if not title.strip() or not dedup_key.strip():
+        raise ValueError("title and dedup_key are required")
+
+    with _suggestions_lock:
+        suggestions = _load_raw().get("suggestions", [])
+
+        # Never re-offer something the user already saw and decided on, and
+        # never duplicate a still-pending proposal.
+        for existing in suggestions:
+            if existing.get("dedup_key") == dedup_key:
+                if existing.get("status") in (_STATUS_DISMISSED, _STATUS_ACCEPTED):
+                    return None
+                if existing.get("status") == _STATUS_PENDING:
+                    return None
+
+        pending_count = sum(1 for s in suggestions if s.get("status") == _STATUS_PENDING)
+        if pending_count >= MAX_PENDING:
+            logger.info("Suggestion backlog full (%d); dropping %r", MAX_PENDING, title)
+            return None
+
+        record = {
+            "id": uuid.uuid4().hex[:12],
+            "title": title.strip(),
+            "description": description.strip(),
+            "source": source,
+            "job_spec": job_spec,
+            "dedup_key": dedup_key.strip(),
+            "status": _STATUS_PENDING,
+            "created_at": _hermes_now().isoformat(),
+        }
+        suggestions.append(record)
+        _save_raw(suggestions)
+        return record
+
+
+def get_suggestion(ref: str) -> Optional[Dict[str, Any]]:
+    """Resolve a suggestion by id, 1-based pending index, or title (exact)."""
+    suggestions = load_suggestions()
+    # By id.
+    for s in suggestions:
+        if s.get("id") == ref:
+            return s
+    # By 1-based pending index.
+    if ref.isdigit():
+        pending = [s for s in suggestions if s.get("status") == _STATUS_PENDING]
+        idx = int(ref) - 1
+        if 0 <= idx < len(pending):
+            return pending[idx]
+    # By exact title (case-insensitive).
+    for s in suggestions:
+        if s.get("title", "").lower() == ref.lower():
+            return s
+    return None
+
+
+def _set_status(suggestion_id: str, status: str) -> bool:
+    with _suggestions_lock:
+        suggestions = _load_raw().get("suggestions", [])
+        changed = False
+        for s in suggestions:
+            if s.get("id") == suggestion_id:
+                s["status"] = status
+                s["resolved_at"] = _hermes_now().isoformat()
+                changed = True
+                break
+        if changed:
+            _save_raw(suggestions)
+        return changed
+
+
+def dismiss_suggestion(ref: str) -> bool:
+    """Dismiss a suggestion (latched — never re-offered for its dedup_key)."""
+    s = get_suggestion(ref)
+    if not s:
+        return False
+    return _set_status(s["id"], _STATUS_DISMISSED)
+
+
+def accept_suggestion(ref: str, *, origin: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]:
+    """Accept a suggestion: create the real cron job from its ``job_spec``.
+
+    Returns the created cron job dict, or None if the suggestion isn't found /
+    not pending. The job_spec is passed straight to ``cron.jobs.create_job``;
+    an ``origin`` (platform/chat) is merged so "origin" delivery routes back to
+    the chat where the user accepted.
+    """
+    s = get_suggestion(ref)
+    if not s or s.get("status") != _STATUS_PENDING:
+        return None
+
+    from cron.jobs import create_job
+
+    spec = dict(s.get("job_spec") or {})
+    if origin is not None and "origin" not in spec:
+        spec["origin"] = origin
+
+    job = create_job(**spec)
+    _set_status(s["id"], _STATUS_ACCEPTED)
+    return job
+
+
+def clear_resolved() -> int:
+    """Drop accepted/dismissed records from disk. Returns the count removed.
+
+    Pending suggestions and the dedup memory of dismissed ones are the only
+    things that matter long-term, but dismissed records must be RETAINED for
+    their dedup_key (so they aren't re-offered). This only prunes ACCEPTED
+    records, which have served their purpose once the job exists.
+    """
+    with _suggestions_lock:
+        suggestions = _load_raw().get("suggestions", [])
+        kept = [s for s in suggestions if s.get("status") != _STATUS_ACCEPTED]
+        removed = len(suggestions) - len(kept)
+        if removed:
+            _save_raw(kept)
+        return removed

package/agent/docs/chronos-managed-cron-contract.md

@@ -0,0 +1,196 @@
+# Chronos managed-cron — agent ↔ NAS wire contract
+
+**Status:** authoritative wire spec for the Chronos cron provider.
+**Audience:** the NAS-side implementer of the `agent-cron` endpoints
+(`nous-account-service`) and anyone debugging the managed-cron path.
+
+Chronos lets a hosted Hermes gateway **scale to zero** while idle and still
+fire cron jobs. Instead of an in-process 60-second ticker, the agent asks NAS
+to arm exactly **one external one-shot per job at that job's real next-fire
+time**. NAS calls the agent back at fire time over an authenticated webhook;
+the agent runs the job and re-arms the next one-shot. Between fires the agent
+process can be fully stopped — it wakes only on a genuine fire.
+
+The external scheduler NAS uses to implement the one-shots is an **internal NAS
+implementation detail**. The agent never talks to it, never holds its
+credentials, and never names it. The agent only knows the three NAS endpoints
+below.
+
+```
+create/update/pause/resume/remove a cron job (agent side)
+  │
+  ▼
+ChronosCronScheduler.reconcile()        ── agent computes next_run_at
+  │  POST {portal}/api/agent-cron/provision   (auth: agent's Nous access token)
+  ▼
+NAS arms a one-shot for fire_at         ── NAS owns the scheduler + its creds
+  │
+  ⏰ at fire_at
+  ▼
+scheduler → POST {portal}/api/agent-cron/relay   (auth: scheduler signature, NAS-verified)
+  │
+  ▼
+NAS mints a short-lived agent-audience JWT (purpose=cron_fire)
+  │  POST {agent_callback_url}/api/cron/fire        (auth: that JWT)
+  ▼
+agent verifies the NAS JWT → store CAS claim → run_one_job → re-arm next one-shot
+```
+
+## Trust model (read this first)
+
+| Hop | Who calls whom | Auth mechanism | Verified by |
+|---|---|---|---|
+| 1 | agent → NAS (`provision`/`cancel`/`list`) | the agent's existing **Nous Portal access token** (Bearer) | NAS (its normal agent-token path) |
+| 2 | scheduler → NAS (`relay`) | the scheduler's request **signature** | NAS (the signature path it already has) |
+| 3 | NAS → agent (`/api/cron/fire`) | a **short-lived NAS-minted JWT** (`aud=agent:{instance_id}`, `purpose=cron_fire`) | agent (PyJWT against NAS JWKS) |
+
+Why NAS-mediated rather than scheduler→agent direct: the scheduler signs with
+**NAS's** keys, which the agent does not (and should not) hold. The agent can
+only verify a **NAS-minted** token — a trust path it already has. This keeps
+all scheduler credentials inside NAS. (Full rationale: the plan's DQ-4.)
+
+No new secret is introduced on the agent: hop 1 reuses the token the agent
+already uses for the portal, and hop 3 reuses the NAS-JWT verification the agent
+already performs.
+
+---
+
+## Endpoint 1 — `POST /api/agent-cron/provision`  (agent → NAS)
+
+Arm (or re-arm, idempotently) exactly one one-shot for a job.
+
+- **Auth:** `Authorization: Bearer <agent Nous access token>`. NAS validates via
+  its normal agent-token path and scopes the row to the calling agent/org.
+- **Request body:**
+  ```json
+  {
+    "job_id": "ab12cd34",
+    "fire_at": "2026-06-18T12:34:56+00:00",
+    "agent_callback_url": "https://agent-xyz.fly.dev",
+    "dedup_key": "ab12cd34:2026-06-18T12:34:56+00:00"
+  }
+  ```
+  - `fire_at` — ISO 8601, **agent-computed**. May be sub-minute in the future;
+    NAS must honor second-granularity (the agent owns the time, so there is no
+    1-minute scheduler floor).
+  - `agent_callback_url` — the agent's own publicly-reachable base URL. NAS
+    POSTs `{agent_callback_url}/api/cron/fire` at fire time.
+  - `dedup_key` — `"{job_id}:{fire_at}"`. NAS **upserts by `(agent_id, job_id)`**
+    so re-arming the same fire is idempotent (no duplicate one-shots). A new
+    `fire_at` for the same `job_id` replaces the prior arm.
+- **Action:** arm one one-shot to fire at `fire_at`, destined for the NAS
+  **relay** route (Endpoint 3) — NOT the agent directly, so NAS stays in the
+  loop to mint the agent JWT. Persist `(agent_id, job_id, schedule_id,
+  agent_callback_url)`.
+- **Response:** `200 {"schedule_id": "<opaque>"}`.
+
+## Endpoint 2 — `POST /api/agent-cron/cancel`  (agent → NAS)
+
+- **Auth:** same as Endpoint 1.
+- **Body:** `{"job_id": "ab12cd34"}`.
+- **Action:** cancel the armed one-shot for `(agent_id, job_id)` and delete the
+  row. Idempotent — cancelling an unknown job is a 200 no-op.
+- **Response:** `200 {"ok": true}`.
+
+## Endpoint 3 — `POST /api/agent-cron/relay`  (scheduler → NAS, the fire relay)
+
+- **Auth:** the scheduler's request **signature**, verified by NAS with the
+  signature path it already has. This is the trust boundary for the fire — a
+  forged relay call must be rejected here.
+- **Action:**
+  1. Look up `(agent_id, job_id) → agent_callback_url` from the persisted row.
+  2. Mint a **short-lived** JWT: `aud = "agent:{instance_id}"`,
+     `iss = {portal_url}`, `purpose = "cron_fire"`, small `exp` (≈60–120s),
+     signed with NAS's normal asymmetric signing key (published via JWKS).
+  3. `POST {agent_callback_url}/api/cron/fire` with
+     `Authorization: Bearer <that JWT>` and body `{"job_id": "...", "fire_at": "..."}`.
+  4. Treat a non-2xx agent response as a **retryable** failure (let the
+     scheduler retry the relay). The agent's store CAS de-dupes a double fire,
+     so retries are safe.
+- **Response to the scheduler:** 2xx once the agent POST is accepted (202), so
+  the scheduler does not retry a delivered fire.
+
+---
+
+## Inbound `POST /api/cron/fire`  (NAS → agent) — agent side, already implemented
+
+This is the agent endpoint NAS calls in Endpoint 3 step 3. Served by the
+**dashboard app** (`hermes_cli/web_server.py`) — the agent's always-reachable
+public HTTP surface on hosted deployments (the gateway may be idle/scaled down);
+it is in `PUBLIC_API_PATHS` so the dashboard cookie gate lets the bearer-JWT
+callback through to the verifier. (Also registered on the optional
+`APIServerAdapter` for self-host API-server deployments.) The verifier is
+`plugins/cron/chronos/verify.py`.
+
+- **Auth:** `Authorization: Bearer <NAS-minted JWT>`. The agent verifies:
+  - signature against the NAS JWKS (`cron.chronos.nas_jwks_url`),
+  - `aud` == `cron.chronos.expected_audience` (this agent's
+    `agent:{instance_id}`),
+  - `iss` == `cron.chronos.portal_url`,
+  - `exp` / `nbf` (30s leeway),
+  - `purpose == "cron_fire"` — a general agent JWT (no/other purpose) is
+    rejected so it can't be replayed against this endpoint.
+- **Body:** `{"job_id": "ab12cd34", "fire_at": "..."}` (only `job_id` is used).
+- **Behavior:**
+  - invalid/missing/forged/expired/wrong-aud/wrong-purpose token → **401**, no
+    execution.
+  - missing `job_id` → **400**.
+  - valid → **202 `{"status": "accepted", "job_id": "..."}`** immediately, and
+    the job runs in the background. 202-before-run means a long agent turn never
+    trips the relay's HTTP timeout.
+- **At-most-once:** the agent claims the job with a store-level compare-and-set
+  (`claim_job_for_fire`) before running. A relay/scheduler retry that arrives
+  while the first fire is in flight (or after it completed) loses the claim and
+  does not double-run.
+
+---
+
+## At-most-once & re-arm semantics
+
+- **Recurring (cron/interval):** on fire, the agent advances `next_run_at`
+  (under its store lock) as part of the claim, runs the job, then re-provisions
+  a one-shot for the new `next_run_at`. A duplicate relay for the old `fire_at`
+  finds the claim taken / time advanced and is dropped.
+- **One-shot (`30m`, `+90s`, etc.):** fires once; `mark_job_run` marks it
+  completed. No re-arm.
+- **`repeat.times = N`:** `mark_job_run` deletes the job at the limit, so
+  `get_job` returns `None` after the final fire → the agent does **not** re-arm
+  → the schedule stops cleanly with no orphaned one-shot.
+- **Multi-replica agents:** the store CAS makes the fire at-most-once across N
+  gateway replicas sharing one `HERMES_HOME` — exactly one replica runs each
+  fire.
+
+## Reconcile (self-healing)
+
+The agent reconciles desired (`jobs.json`) vs armed on:
+- `start()` (gateway boot / wake),
+- every successful job mutation (`on_jobs_changed`),
+- piggybacked after each fire (re-arm).
+
+Reconcile arms missing/changed-time jobs and cancels orphans. A missed
+provision (transient NAS error) self-heals on the next reconcile. There is **no
+periodic wake** of a sleeping agent — that would negate scale-to-zero.
+
+## Config (agent side)
+
+All non-secret (`cron.chronos.*` in `config.yaml`); the agent holds no scheduler
+credentials. For hosted agents NAS sets these at provision time:
+
+| key | meaning |
+|---|---|
+| `cron.provider` | `"chronos"` to activate (empty = built-in ticker) |
+| `cron.chronos.portal_url` | NAS base URL (also the expected JWT `iss`) |
+| `cron.chronos.callback_url` | the agent's own public base URL for NAS→agent fires |
+| `cron.chronos.expected_audience` | this agent's JWT `aud` (`agent:{instance_id}`) |
+| `cron.chronos.nas_jwks_url` | NAS JWKS for verifying the fire JWT |
+
+If `callback_url` / `portal_url` is blank or the agent has no Nous login,
+`is_available()` returns False and the resolver falls back to the built-in
+in-process ticker — cron never loses its trigger.
+
+## Escape hatch (not default)
+
+The inbound `/api/cron/fire` verifier is pluggable (`get_fire_verifier()`). If
+relay volume through NAS ever saturates, a direct scheduler→agent mode with a
+per-job NAS-minted cron-key can replace the NAS-JWT verifier with **no change to
+the webhook handler**. NAS-mediated (this contract) is the default.

package/agent/docs/design/profile-builder.md

@@ -0,0 +1,146 @@
+# Profile Builder — Dashboard-Native, Full-Featured Profile Creation
+
+Status: design proposal (not yet implemented)
+Author: drafted for Teknium
+Supersedes: PR #31781 (prompt_toolkit `hermes profile wizard`)
+
+## Why this, not the CLI wizard
+
+PR #31781 added a keyboard-driven `hermes profile wizard` in the terminal.
+The decision is to **not** build the profile-creation experience in the CLI.
+The dashboard already owns mature, separate pages for every element a profile
+needs, and a profile is just a HERMES_HOME directory — so the dashboard is the
+right home for a full-featured builder, and it can reuse everything that
+already exists.
+
+A profile = a full `~/.hermes/profiles/<name>/` directory with its own:
+- `config.yaml` — holds `model`/`provider`, `mcp_servers`, enabled skills
+- `skills/` — physical SKILL.md files (built-in seed + optional + hub installs)
+- `.env` — secrets
+- `SOUL.md` / `USER.md` — identity
+
+So per-profile scoping of Model, MCPs, and Skills is **native** — no data-model
+change needed. The gap is purely UX: creation today is a thin modal
+(name + clone + model + description), and you can only compose skills/MCPs
+*after* the profile exists, by visiting other pages and remembering to scope
+them.
+
+## What already exists (reuse, don't rebuild)
+
+| Element | Existing page | Existing API | Profile-scopable? |
+|---|---|---|---|
+| Name / Description | ProfilesPage create modal | `POST /api/profiles` (`create_profile`) | yes (args) |
+| Model + Provider | ModelsPage | `_write_profile_model(profile_dir, …)` | yes — HERMES_HOME override, already wired into create endpoint |
+| MCPs | McpPage | `mcp_config._save_mcp_server` + `/api/mcp/catalog` | yes — wrap with HERMES_HOME override |
+| Skills (built-in/optional) | SkillsPage | `GET /api/skills`, `/api/skills/toggle` | yes — config write |
+| Skills (hub) | SkillsPage | `/api/skills/hub/search`, `/api/skills/hub/install` | **only via subprocess** — see seam #1 |
+
+## Two architectural seams found while grounding this design
+
+These are load-bearing — they change the implementation, not just the polish.
+
+### Seam #1 — hub-skill install cannot use the HERMES_HOME override
+
+`tools/skills_hub.py` binds `SKILLS_DIR = HERMES_HOME / "skills"` at **module
+import time**. The context-local `set_hermes_home_override()` swap (which makes
+`_write_profile_model` and the MCP write land in the target profile) does NOT
+retroactively rebind that already-imported module global. So a data-layer wrap
+of hub install would write into the dashboard's *own* active profile, not the
+new one.
+
+The correct mechanism is the existing subprocess path: `_spawn_hermes_action`
+runs `python -m hermes_cli.main <subcommand>`, and `_apply_profile_override()`
+re-reads `sys.argv` at import in the fresh child. Prepend `-p <profile>`:
+
+```python
+_spawn_hermes_action(["-p", profile, "skills", "install", identifier], "skills-install")
+```
+
+A fresh subprocess re-imports `skills_hub` with the profile's HERMES_HOME bound
+from the start, so `SKILLS_DIR` resolves to `<profile>/skills/`. Correct by
+construction.
+
+### Seam #2 — hub installs are async, so create cannot be fully atomic
+
+Built-in/optional skill enabling and MCP writes are **synchronous config ops**
+and can be part of the create call. Hub installs are long-running git fetches
+spawned detached (`_spawn_hermes_action` returns a PID immediately). So the
+create flow is:
+
+1. `create_profile()` — make the dir (synchronous)
+2. write model (synchronous, HERMES_HOME override)
+3. write selected MCP servers (synchronous, HERMES_HOME override)
+4. seed/enable selected built-in + optional skills (synchronous)
+5. spawn `hermes -p <profile> skills install <id>` per hub skill (async, returns PIDs)
+
+Steps 1–4 commit before the response; step 5 returns a list of action PIDs the
+UI polls (same pattern as today's SkillsPage hub install). The builder's
+"Review → Create" returns `{ok, name, path, hub_installs: [{id, pid}]}` and the
+final screen shows live install progress for the hub skills.
+
+## Proposed backend change (small, follows existing patterns)
+
+Extend `ProfileCreate` and the create endpoint — no new endpoints, no rewrite:
+
+```python
+class ProfileCreate(BaseModel):
+    name: str
+    clone_from: Optional[str] = None
+    # Backward compatibility for older dashboard/desktop clients.
+    clone_from_default: bool = False
+    clone_all: bool = False
+    no_skills: bool = False
+    description: Optional[str] = None
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    # NEW — all optional, all best-effort post-create (profile already exists)
+    mcp_servers: List[MCPServerCreate] = []      # synchronous, HERMES_HOME override
+    builtin_skills: List[str] = []               # synchronous enable/seed
+    hub_skills: List[str] = []                   # async spawn, returns PIDs
+```
+
+The endpoint already does best-effort post-create steps (`seed_profile_skills`,
+`_write_profile_model`). Add two more best-effort blocks (MCP write, hub-skill
+spawn) in the same style — a failure in any of them must not 500 the create,
+since the profile dir already exists and the user can fix it from the relevant
+page afterward. Mirror `_write_profile_model`'s HERMES_HOME-override helper for
+the MCP write (`_write_profile_mcp_servers(profile_dir, servers)`).
+
+## Proposed frontend — dedicated builder page `/profiles/new`
+
+A full page (not the cramped modal), stepped, each step reusing the existing
+page's component + API, targeted at the new profile:
+
+```
+① Identity   Name + Description (+ optional clone-from existing profile)
+② Model      Provider + model picker  (reuse ModelsPage picker)
+③ Skills     Tabs: Built-in · Optional · Hub-search
+             multi-select; "Start from default bundle" preset button
+④ MCPs       Tabs: Catalog browse · Manual add  (reuse McpPage form)
+⑤ Review     Blueprint preview → Create
+             → progress screen for async hub installs
+```
+
+Nothing writes to disk until ⑤.
+
+## Open product decisions (need Teknium)
+
+1. **Skills seeding default.** Fresh profiles auto-seed the default bundle
+   today. In the builder, should the skill step **replace** the bundle (pick
+   exactly what you want; offer a "start from default bundle" preset) or
+   **augment** it? Recommendation: replace + preset button.
+
+2. **Page vs richer modal.** Dedicated `/profiles/new` page (room to grow:
+   SOUL editing, multi-agent fleets later) vs a bigger create modal on
+   ProfilesPage. Recommendation: dedicated page — matches "full-featured / way
+   more options."
+
+## Verification plan (when built)
+
+- Backend E2E with isolated HERMES_HOME: POST a full create body
+  (name + model + 2 MCPs + 3 builtin skills + 1 hub skill), assert the new
+  profile dir has the model in config.yaml, both MCP servers in config.yaml,
+  the builtin skills enabled, and a spawned PID for the hub skill. Negative:
+  a bad MCP entry must not 500 the create.
+- `cd web && npm run build` (no JS test suite in web/).
+- Targeted: `pytest tests/<web_server profile tests> -k profile_create`.