@smilintux/skcapstone 0.9.0 → 0.12.5

package/src/skcapstone/cli/memory.py

@@ -423,7 +423,7 @@ def register_memory_commands(main: click.Group) -> None:
     @memory.command("rehydrate")
     @click.option("--home", default=AGENT_HOME, type=click.Path())
     @click.option("--agent", "-a", default=None,
-                  help="Agent name (default: SKCAPSTONE_AGENT or 'lumina').")
+                  help="Agent name (default: active agent).")
     @click.option("--febs-only", is_flag=True, help="Only ingest FEB files (trust rehydration).")
     @click.option("--memories-only", is_flag=True, help="Only ingest flat-file memories into backends.")
     @click.option("--force", is_flag=True, help="Re-ingest even if already in backend.")
@@ -439,7 +439,9 @@ def register_memory_commands(main: click.Group) -> None:
         import os
         from ..models import MemoryLayer
 
-        agent_name = agent or os.environ.get("SKCAPSTONE_AGENT", "lumina")
+        from .. import active_agent_name
+
+        agent_name = agent or os.environ.get("SKCAPSTONE_AGENT") or active_agent_name()
         home_path = Path(home).expanduser()
         agent_home = home_path / "agents" / agent_name
 
@@ -463,8 +465,8 @@ def register_memory_commands(main: click.Group) -> None:
             try:
                 from ..memory_adapter import get_unified, entry_to_memory
                 unified = get_unified()
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Memory adapter unavailable, falling back to file-only mode: %s", exc)
 
             for layer in MemoryLayer:
                 layer_dir = mem_dir / layer.value
@@ -481,8 +483,8 @@ def register_memory_commands(main: click.Group) -> None:
                                 if existing:
                                     skipped += 1
                                     continue
-                            except Exception:
-                                pass
+                            except Exception as exc:
+                                logger.debug("Failed to check existing memory %s: %s", mem_id, exc)
 
                         if unified:
                             from ..models import MemoryEntry

package/src/skcapstone/cli/peers_dir.py

@@ -19,7 +19,7 @@ def register_peers_dir_commands(main: click.Group) -> None:
     def peers_dir():
         """Peer transport directory — routing addresses for the mesh.
 
-        SKComm transport endpoints. For identity/trust peers, see 'peer'."""
+        SKComms transport endpoints. For identity/trust peers, see 'peer'."""
 
     @peers_dir.command("list")
     @click.option("--home", "sk_home", default=AGENT_HOME, type=click.Path())

package/src/skcapstone/cli/register_cmd.py

@@ -1,7 +1,7 @@
 """Register command — auto-register SK* skills and MCP servers.
 
 Detects the user's environments (OpenClaw, Claude Code, Cursor, VS Code,
-OpenCode CLI, mcporter) and registers SKILL.md symlinks + MCP server entries.
+OpenCode CLI, Codex, mcporter) and registers SKILL.md symlinks + MCP server entries.
 
 Commands:
     skcapstone register              — register all SK* packages
@@ -49,7 +49,7 @@ def register_register_commands(main: click.Group) -> None:
         """Register all SK* skills and MCP servers in detected environments.
 
         Auto-detects your development environments (Claude Code, Cursor,
-        VS Code, OpenClaw, OpenCode, mcporter) and ensures all SK* skill
+        VS Code, OpenClaw, OpenCode, Codex, mcporter) and ensures all SK* skill
         manifests and MCP server entries are properly configured.
 
         Examples:
@@ -91,12 +91,23 @@ def register_register_commands(main: click.Group) -> None:
             dry_run=dry_run,
         )
 
+        # Register Claude Code hooks
+        if not dry_run:
+            try:
+                from skmemory.register import register_hooks
+                register_hooks(install_hooks=True)
+            except ImportError:
+                pass
+            except Exception:
+                pass
+
         # Display results
         from rich.table import Table
 
         table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
         table.add_column("Package", style="cyan")
         table.add_column("Skill", style="dim")
+        table.add_column("Codex")
         table.add_column("MCP")
         table.add_column("OpenClaw Plugin")
 
@@ -133,6 +144,21 @@ def register_register_commands(main: click.Group) -> None:
             else:
                 mcp_str = str(mcp_info)
 
+            codex_info = pkg_result.get("codex_skill", {})
+            codex_action = codex_info.get("action", "")
+            if codex_action == "created":
+                codex_str = "[green]created[/]"
+            elif codex_action == "exists":
+                codex_str = "[dim]exists[/]"
+            elif codex_action == "dry-run":
+                codex_str = "[yellow]would create[/]"
+            elif codex_action == "error":
+                codex_str = f"[red]{codex_info.get('error', 'error')}[/]"
+            elif not codex_action:
+                codex_str = "[dim]—[/]"
+            else:
+                codex_str = f"[dim]{codex_action}[/]"
+
             plugin_action = pkg_result.get("openclaw_plugin", "")
             if plugin_action == "created":
                 plugin_str = "[green]created[/]"
@@ -147,7 +173,7 @@ def register_register_commands(main: click.Group) -> None:
             else:
                 plugin_str = f"[dim]{plugin_action}[/]"
 
-            table.add_row(name, skill_str, mcp_str, plugin_str)
+            table.add_row(name, skill_str, codex_str, mcp_str, plugin_str)
 
         console.print(table)
         console.print()

package/src/skcapstone/cli/scheduler_cmd.py

@@ -0,0 +1,167 @@
+"""`skcapstone scheduler` — manage the unified job scheduler."""
+from __future__ import annotations
+
+import json
+import os
+import socket
+from pathlib import Path
+
+import click
+
+from .. import AGENT_HOME
+from ..scheduler_jobs import (
+    load_jobs,
+    load_jobs_with_dropins,
+    current_host_aliases,
+    job_runs_here,
+)
+from ..scheduler_runner import JobRunner
+from ..scheduler_state import SchedulerState
+
+
+def _home() -> Path:
+    """Return the effective SKCAPSTONE_HOME path.
+
+    Reads from the ``SKCAPSTONE_HOME`` environment variable when set,
+    falling back to the package-level ``AGENT_HOME`` constant.
+
+    Returns:
+        Resolved :class:`~pathlib.Path` for the agent home directory.
+    """
+    return Path(os.environ.get("SKCAPSTONE_HOME", AGENT_HOME))
+
+
+def _jobs_path() -> Path:
+    """Return the path to the synced ``jobs.yaml`` registry.
+
+    Returns:
+        ``<SKCAPSTONE_HOME>/config/jobs.yaml`` as a :class:`~pathlib.Path`.
+    """
+    return _home() / "config" / "jobs.yaml"
+
+
+def register_scheduler_commands(main: click.Group) -> None:
+    """Register the ``scheduler`` command group onto *main*.
+
+    Adds the following sub-commands:
+
+    - ``scheduler list``   — list all configured jobs with run status.
+    - ``scheduler status`` — show last-run state for this node.
+    - ``scheduler run``    — execute a job immediately.
+    - ``scheduler logs``   — tail the most recent log for a job.
+    - ``scheduler enable`` — enable a job in ``jobs.yaml``.
+    - ``scheduler disable`` — disable a job in ``jobs.yaml``.
+
+    Args:
+        main: The top-level :class:`click.Group` to attach commands to.
+    """
+
+    @main.group("scheduler")
+    def scheduler() -> None:
+        """Manage the unified job scheduler (skscheduler)."""
+
+    @scheduler.command("list")
+    def list_jobs() -> None:
+        """List all configured jobs and where they run."""
+        jobs = load_jobs_with_dropins(_jobs_path())
+        if not jobs:
+            click.echo("No jobs configured.")
+            return
+        here = current_host_aliases()
+        for j in jobs:
+            sched = j.schedule or (f"every {int(j.every_seconds)}s" if j.every_seconds else "-")
+            mark = "x" if (j.enabled and job_runs_here(j, here)) else " "
+            click.echo(f"[{mark}] {j.name:24s} {j.type:6s} {sched:18s} nodes={j.nodes}")
+
+    @scheduler.command("status")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+    def status(as_json: bool) -> None:
+        """Show last-run status for this node."""
+        st = SchedulerState(root=_home(), hostname=socket.gethostname())
+        data = st.all()
+        if as_json:
+            click.echo(json.dumps(data, indent=2))
+            return
+        if not data:
+            click.echo("No run history on this node yet.")
+            return
+        for name, rec in data.items():
+            click.echo(
+                f"{name:24s} last={rec.get('last_run')} status={rec.get('last_status')} "
+                f"runs={rec.get('run_count')} errors={rec.get('error_count')}"
+            )
+
+    @scheduler.command("run")
+    @click.argument("job_name")
+    def run_now(job_name: str) -> None:
+        """Run a job now on this node (manual override; ignores schedule and affinity)."""
+        jobs = {j.name: j for j in load_jobs_with_dropins(_jobs_path())}
+        job = jobs.get(job_name)
+        if not job:
+            raise click.ClickException(f"Unknown job: {job_name}")
+        runner = JobRunner(log_dir=_home() / "scheduler" / socket.gethostname() / "logs")
+        result = runner.run(job)
+        # Record state + fire the job's notify policy so a manual run is observable in
+        # `scheduler status` and exercises the sk-alert hook (same as the scheduled path).
+        from datetime import datetime, timezone
+        from ..scheduled_tasks import TaskScheduler
+        SchedulerState(_home(), socket.gethostname()).record_run(
+            job.name, now=datetime.now(timezone.utc), ok=result.ok, error=result.error)
+        TaskScheduler._maybe_notify(job, result, attempts=1)
+        if result.output:
+            click.echo(result.output.strip())
+        if not result.ok:
+            raise click.ClickException(f"Job failed: {result.error}")
+        click.echo(f"OK {job_name} done")
+
+    @scheduler.command("logs")
+    @click.argument("job_name")
+    @click.option("--tail", default=40, show_default=True, help="Number of lines to show.")
+    def logs(job_name: str, tail: int) -> None:
+        """Show the latest log for a job on this node."""
+        log_dir = _home() / "scheduler" / socket.gethostname() / "logs"
+        matches = sorted(log_dir.glob(f"{job_name}-*.log")) if log_dir.exists() else []
+        if not matches:
+            click.echo(f"No logs for '{job_name}'.")
+            return
+        lines = matches[-1].read_text(encoding="utf-8").splitlines()
+        click.echo("\n".join(lines[-tail:]))
+
+    @scheduler.command("enable")
+    @click.argument("job_name")
+    def enable(job_name: str) -> None:
+        """Enable a job (sets enabled: true in jobs.yaml)."""
+        _set_enabled(job_name, True)
+        click.echo(f"enabled {job_name}")
+
+    @scheduler.command("disable")
+    @click.argument("job_name")
+    def disable(job_name: str) -> None:
+        """Disable a job (sets enabled: false in jobs.yaml)."""
+        _set_enabled(job_name, False)
+        click.echo(f"disabled {job_name}")
+
+
+def _set_enabled(job_name: str, value: bool) -> None:
+    """Set the ``enabled`` flag for *job_name* in ``jobs.yaml``.
+
+    Reads the current ``jobs.yaml``, toggles the ``enabled`` field for the
+    named job, and writes the file back atomically via
+    :func:`yaml.safe_dump`.
+
+    Args:
+        job_name: The job key to update.
+        value: ``True`` to enable the job; ``False`` to disable.
+
+    Raises:
+        click.ClickException: If *job_name* is not found in the config.
+    """
+    import yaml
+
+    path = _jobs_path()
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    jobs = data.get("jobs") or {}
+    if job_name not in jobs:
+        raise click.ClickException(f"Unknown job: {job_name}")
+    jobs[job_name]["enabled"] = value
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")

package/src/skcapstone/cli/session.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import sys
 from pathlib import Path
 
@@ -125,3 +126,27 @@ def register_session_commands(main: click.Group) -> None:
         for src, count in sorted(by_source.items(), key=lambda x: -x[1]):
             console.print(f"    {src}: {count}")
         console.print()
+
+    @session.command("briefing")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option(
+        "--format",
+        "fmt",
+        type=click.Choice(["text", "json"]),
+        default="text",
+        help="Output format (default: text).",
+    )
+    @click.option("--memories", "-n", default=10, help="Max recent memories to include.")
+    def session_briefing(home: str, fmt: str, memories: int):
+        """Show a native startup briefing for sovereign sessions.
+
+        Merges SKCapstone context with the current HammerTime legal/case
+        briefing when available, so any client can consume one startup payload.
+        """
+        from ..session_briefing import build_session_briefing, format_session_briefing_text
+
+        payload = build_session_briefing(Path(home).expanduser(), memory_limit=memories)
+        if fmt == "json":
+            click.echo(json.dumps(payload, indent=2, default=str))
+            return
+        click.echo(format_session_briefing_text(payload))

package/src/skcapstone/cli/setup.py

@@ -26,16 +26,23 @@ from ..runtime import get_runtime
 from rich.panel import Panel
 
 
+def _get_claude_template_dir() -> Path:
+    """Return the bundled defaults/claude skeleton directory."""
+    return Path(__file__).parent.parent / "defaults" / "claude"
+
+
 def _write_global_claude_md(home_path: Path, agent_name: str) -> Optional[Path]:
-    """Write ~/.claude/CLAUDE.md so Claude Code auto-rehydrates on every session."""
+    """Write ~/.claude/CLAUDE.md from the bundled skeleton template.
+
+    The template lives at defaults/claude/CLAUDE.md inside the package.
+    {{AGENT_NAME}} is substituted with the actual agent name.
+    If the template is missing, falls back to a minimal generated file.
+    """
     import platform
 
     if platform.system() == "Windows":
         appdata = os.environ.get("APPDATA", "")
-        if appdata:
-            claude_dir = Path(appdata) / ".claude"
-        else:
-            claude_dir = Path.home() / "AppData" / "Roaming" / ".claude"
+        claude_dir = Path(appdata) / ".claude" if appdata else Path.home() / "AppData" / "Roaming" / ".claude"
     else:
         claude_dir = Path.home() / ".claude"
 
@@ -43,30 +50,20 @@ def _write_global_claude_md(home_path: Path, agent_name: str) -> Optional[Path]:
         claude_dir.mkdir(parents=True, exist_ok=True)
         claude_md = claude_dir / "CLAUDE.md"
 
-        content = (
-            f"# Claude Code — Global Agent Instructions ({agent_name})\n\n"
-            "## SKCapstone Auto-Rehydration\n\n"
-            "At the start of every new session, run these commands in order:\n\n"
-            "```bash\n"
-            "skcapstone trust rehydrate\n"
-            "skcapstone sync pull\n"
-            "skcapstone status\n"
-            "```\n\n"
-            "## Agent Details\n\n"
-            f"- **Name**: {agent_name}\n"
-            f"- **Home**: `{home_path}`\n\n"
-            "## Quick Reference\n\n"
-            "```bash\n"
-            "skcapstone status                          # full pillar status\n"
-            "skcapstone memory list                     # recent memories\n"
-            "skcapstone sync push                       # push state to peers\n"
-            "skcapstone context show --format claude-md # regenerate this file\n"
-            "skcapstone sync pair --export-pubkey       # export your GPG pubkey\n"
-            "skcapstone sync pair --import-pubkey <f>   # import a peer's pubkey\n"
-            "```\n\n"
-            "> Auto-generated by `skcapstone init`. "
-            "Regenerate with: `skcapstone context generate --target claude-md`\n"
-        )
+        template_path = _get_claude_template_dir() / "CLAUDE.md"
+        if template_path.exists():
+            content = template_path.read_text(encoding="utf-8")
+            content = content.replace("{{AGENT_NAME}}", agent_name)
+        else:
+            # Minimal fallback if template is missing
+            content = (
+                f"# Claude Code — Global Agent Instructions ({agent_name})\n\n"
+                f"- **Agent**: `{agent_name}`\n"
+                f"- **Home**: `{home_path}`\n"
+                f"- **Env**: `SKCAPSTONE_AGENT={agent_name}`\n\n"
+                "Hooks auto-inject on SessionStart: soul + FEB chain + memories.\n\n"
+                "> Regenerate with: `skcapstone context generate --target claude-md`\n"
+            )
 
         claude_md.write_text(content, encoding="utf-8")
         return claude_md
@@ -74,6 +71,76 @@ def _write_global_claude_md(home_path: Path, agent_name: str) -> Optional[Path]:
         return None
 
 
+def _write_claude_settings(merge: bool = True) -> Optional[Path]:
+    """Write (or merge) ~/.claude/settings.json with SK hook registrations.
+
+    Uses the bundled defaults/claude/settings.json template, substituting
+    {{SKMEMORY_HOOKS_DIR}} with the real skmemory hooks path.
+
+    Args:
+        merge: If True and settings.json already exists, merge hooks rather
+               than overwrite. Default True.
+
+    Returns:
+        Path to the written settings.json, or None on failure.
+    """
+    import platform
+
+    if platform.system() == "Windows":
+        appdata = os.environ.get("APPDATA", "")
+        claude_dir = Path(appdata) / ".claude" if appdata else Path.home() / "AppData" / "Roaming" / ".claude"
+    else:
+        claude_dir = Path.home() / ".claude"
+
+    try:
+        import skmemory
+        hooks_dir = str(Path(skmemory.__file__).parent / "hooks")
+    except ImportError:
+        return None  # skmemory not installed — caller should use skmemory register instead
+
+    template_path = _get_claude_template_dir() / "settings.json"
+    if not template_path.exists():
+        return None
+
+    raw = template_path.read_text(encoding="utf-8")
+    raw = raw.replace("{{SKMEMORY_HOOKS_DIR}}", hooks_dir)
+    new_settings = json.loads(raw)
+
+    settings_path = claude_dir / "settings.json"
+    if merge and settings_path.exists():
+        try:
+            existing = json.loads(settings_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+        # Merge hooks: add new hooks that aren't already registered
+        existing_hooks = existing.get("hooks", {})
+        for event, hook_groups in new_settings.get("hooks", {}).items():
+            existing_event = existing_hooks.setdefault(event, [])
+            existing_commands = {
+                h.get("command")
+                for group in existing_event
+                for h in group.get("hooks", [])
+                if "command" in h
+            }
+            for group in hook_groups:
+                cmds = {h.get("command") for h in group.get("hooks", []) if "command" in h}
+                if not cmds.issubset(existing_commands):
+                    existing_event.append(group)
+        existing["hooks"] = existing_hooks
+        # Preserve non-hook keys from template (skipDangerousModePermissionPrompt, etc.)
+        for k, v in new_settings.items():
+            if k != "hooks":
+                existing.setdefault(k, v)
+        final = existing
+    else:
+        claude_dir.mkdir(parents=True, exist_ok=True)
+        final = new_settings
+
+    settings_path.write_text(json.dumps(final, indent=2), encoding="utf-8")
+    return settings_path
+
+
 def register_setup_commands(main: click.Group) -> None:
     """Register all setup/lifecycle commands on the main CLI group."""
 

package/src/skcapstone/cli/shell_cmd.py

@@ -2,13 +2,29 @@
 
 from __future__ import annotations
 
+import sys
+from importlib.resources import as_file, files
+from pathlib import Path
+
 import click
 
 from ._common import AGENT_HOME
 
 
+def _picker_path() -> Path:
+    """Resolve the absolute path to the bundled sk-agent-picker.sh.
+
+    Works for any install layout (PyPI wheel, editable, install.sh) by
+    going through importlib.resources, so the picker is always sourced
+    from inside the installed skcapstone package.
+    """
+    resource = files("skcapstone") / "data" / "sk-agent-picker.sh"
+    with as_file(resource) as p:
+        return Path(p)
+
+
 def register_shell_commands(main: click.Group) -> None:
-    """Register the 'shell' command on the main CLI group."""
+    """Register the 'shell', 'shell-init', and 'shell-picker-path' commands."""
 
     @main.command("shell")
     @click.option(
@@ -41,3 +57,39 @@ def register_shell_commands(main: click.Group) -> None:
         from ..shell import run_shell
 
         run_shell(home=home)
+
+    @main.command("shell-init")
+    def shell_init_cmd() -> None:
+        """Emit shell code that loads the SK agent picker.
+
+        Add to your ~/.bashrc (or ~/.zshrc):
+
+            eval "$(skcapstone shell-init)"
+
+        This sources the picker shipped inside the skcapstone package,
+        so a single `pip install skcapstone` (PyPI, editable, or via
+        install.sh) is enough — no external script copy required.
+        """
+        from .. import DEFAULT_AGENT
+
+        path = _picker_path()
+        if not path.is_file():
+            click.echo(f"# skcapstone: picker missing at {path}", err=True)
+            sys.exit(1)
+        # Propagate the canonical default agent (single source of truth lives
+        # in skcapstone.DEFAULT_AGENT) so the picker and every child process
+        # inherit one authoritative value without re-hardcoding it in shell.
+        click.echo(f'export SK_DEFAULT_AGENT="{DEFAULT_AGENT}"')
+        click.echo(f'source "{path}"')
+
+    @main.command("shell-picker-path")
+    def shell_picker_path_cmd() -> None:
+        """Print the absolute path to the bundled sk-agent-picker.sh.
+
+        Useful for hand-rolled shell wiring, debugging, or scripted
+        invocation of the picker.
+        """
+        path = _picker_path()
+        click.echo(str(path))
+        if not path.is_file():
+            sys.exit(1)

package/src/skcapstone/cli/skills_cmd.py

@@ -114,8 +114,8 @@ def register_skills_commands(main: click.Group) -> None:
                 try:
                     skill_entries = client.search(query) if query else client.list_skills()
                     source = "remote"
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Registry client query failed, falling back: %s", exc)
 
         # 2. Try GitHub raw catalog (always fresh, no server needed)
         if skill_entries is None and not offline:

package/src/skcapstone/cli/soul.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import shutil
 import sys
 from datetime import datetime, timezone
@@ -18,6 +19,8 @@ from .. import SKCAPSTONE_AGENT
 from rich.panel import Panel
 from rich.table import Table
 
+logger = logging.getLogger(__name__)
+
 # Path to the soul-blueprints repository (community blueprints)
 _BLUEPRINTS_REPO = Path.home() / "clawd" / "soul-blueprints" / "blueprints"
 
@@ -61,9 +64,9 @@ def register_soul_commands(main: click.Group) -> None:
         """Reusable --agent/-a option for soul subcommands."""
         return click.option(
             "--agent", "-a",
-            default=SKCAPSTONE_AGENT or "lumina",
-            envvar="SKCAPSTONE_AGENT",
-            help="Agent profile name (default: SKCAPSTONE_AGENT or 'lumina').",
+            default=SKCAPSTONE_AGENT,
+            envvar="SKAGENT",
+            help="Agent profile name (default: SKAGENT or active agent).",
         )
 
     @main.group()
@@ -332,8 +335,8 @@ def register_soul_commands(main: click.Group) -> None:
                 import json
                 base_data = json.loads(base_path.read_text(encoding="utf-8"))
                 vibe = base_data.get("vibe", "")
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Failed to read vibe from soul base.json: %s", exc)
 
         lines = [
             f"Agent: [bold magenta]{agent}[/]",