xrefkit 0.4.4__tar.gz → 0.4.5__tar.gz

{xrefkit-0.4.4 → xrefkit-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.4
+Version: 0.4.5
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -101,6 +101,38 @@ and handoff records from collapsing into one opaque instruction block.
 
 ![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
 
+## Skills: what you can ask XRefKit to do
+
+XRefKit includes Skills for common stages of software and business work. For
+example:
+
+- **Business discovery and planning**: `business_learning_interview`,
+  `business_intake_scoping`, `requirements_flow`, `planning_flow`, and
+  `estimation_flow`
+- **Investigation, design, and implementation**: `investigation_flow`,
+  `source_structure_overview`, `db_current_state_analysis`, `db_design`,
+  `design_flow`, and `implementation_flow`
+- **Constraint and change analysis**: `constraint_derivation_index`,
+  `dotnet_change_analysis`, `code_constraint_derivation`,
+  `cross_constraint_derivation`, and `integration_scenario_derivation`
+- **Review and quality**: `csharp_review`, `python_review`, `security_review`,
+  `test_flow`, `qa_gate_review`, and `review_report_composition`
+- **Knowledge and Skill operations**: `import_skill`, `skill_flow_authoring`,
+  `knowledge_ontology_management`, `judgment_log`, `doc_ship`, and
+  `skill_calibration_evaluation`
+- **Documents and communication**: `pptx_spec_traceability`,
+  `xlsx_spec_traceability`, `presentation_flow_review`, `editorial_intake`,
+  `draft_authoring`, and `marketing_slide_png`
+
+Each Skill is a reusable procedure with a capability/tuning/responsibility
+identity. Its procedure, routing metadata, domain Knowledge, and run evidence
+remain separate. Describe your goal in natural language and XRefKit routes it
+to the relevant Skill; the [Skill catalog](skills/_index.md#xid-8D91F66DDBB7)
+contains the complete current list and summaries.
+
+To install and enable Skills distributed as Python Packages, follow the
+[package-first registration guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+
 ## How It Works
 
 1. Original materials are kept in `sources/`.
@@ -196,6 +228,18 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+For a network deployment without MCP protocol sessions, provide a shared HMAC
+secret and enable stateless HTTP. The client must return the `context_id` from
+`get_startup_context` in `_meta.io.xrefkit/context_id` on later requests:
+
+```powershell
+$env:XREFKIT_CONTEXT_SECRET = 'replace-with-a-managed-secret'
+python -m xrefkit.mcp.server --repo . --transport streamable-http --stateless-http
+```
+
+The context token is signed, repository-bound, and short-lived. It is an
+execution-context token, not a canonical XID or an authorization grant.
+
 ## Skill Run Observation Dashboard
 
 The local dashboard lets a human inspect Skill run status, closure and quality

{xrefkit-0.4.4 → xrefkit-0.4.5}/README.md

@@ -62,6 +62,38 @@ and handoff records from collapsing into one opaque instruction block.
 
 ![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
 
+## Skills: what you can ask XRefKit to do
+
+XRefKit includes Skills for common stages of software and business work. For
+example:
+
+- **Business discovery and planning**: `business_learning_interview`,
+  `business_intake_scoping`, `requirements_flow`, `planning_flow`, and
+  `estimation_flow`
+- **Investigation, design, and implementation**: `investigation_flow`,
+  `source_structure_overview`, `db_current_state_analysis`, `db_design`,
+  `design_flow`, and `implementation_flow`
+- **Constraint and change analysis**: `constraint_derivation_index`,
+  `dotnet_change_analysis`, `code_constraint_derivation`,
+  `cross_constraint_derivation`, and `integration_scenario_derivation`
+- **Review and quality**: `csharp_review`, `python_review`, `security_review`,
+  `test_flow`, `qa_gate_review`, and `review_report_composition`
+- **Knowledge and Skill operations**: `import_skill`, `skill_flow_authoring`,
+  `knowledge_ontology_management`, `judgment_log`, `doc_ship`, and
+  `skill_calibration_evaluation`
+- **Documents and communication**: `pptx_spec_traceability`,
+  `xlsx_spec_traceability`, `presentation_flow_review`, `editorial_intake`,
+  `draft_authoring`, and `marketing_slide_png`
+
+Each Skill is a reusable procedure with a capability/tuning/responsibility
+identity. Its procedure, routing metadata, domain Knowledge, and run evidence
+remain separate. Describe your goal in natural language and XRefKit routes it
+to the relevant Skill; the [Skill catalog](skills/_index.md#xid-8D91F66DDBB7)
+contains the complete current list and summaries.
+
+To install and enable Skills distributed as Python Packages, follow the
+[package-first registration guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+
 ## How It Works
 
 1. Original materials are kept in `sources/`.
@@ -157,6 +189,18 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+For a network deployment without MCP protocol sessions, provide a shared HMAC
+secret and enable stateless HTTP. The client must return the `context_id` from
+`get_startup_context` in `_meta.io.xrefkit/context_id` on later requests:
+
+```powershell
+$env:XREFKIT_CONTEXT_SECRET = 'replace-with-a-managed-secret'
+python -m xrefkit.mcp.server --repo . --transport streamable-http --stateless-http
+```
+
+The context token is signed, repository-bound, and short-lived. It is an
+execution-context token, not a canonical XID or an authorization grant.
+
 ## Skill Run Observation Dashboard
 
 The local dashboard lets a human inspect Skill run status, closure and quality

{xrefkit-0.4.4 → xrefkit-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.4"
+version = "0.4.5"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

{xrefkit-0.4.4 → xrefkit-0.4.5}/tests/test_mcp_setup.py

@@ -55,6 +55,41 @@ def test_mcp_setup_imports_existing_batch_skill_before_writing_report(tmp_path:
     assert payload["output"] == str(output.resolve())
 
 
+def test_mcp_setup_infers_single_skill_id_without_explicit_option(tmp_path: Path, capsys) -> None:
+    source = tmp_path / "existing-skill"
+    source.mkdir()
+    (source / "SKILL.md").write_text("# Existing Skill\n\nUse the supplied workflow.\n", encoding="utf-8")
+    root = tmp_path / "repo"
+    output = tmp_path / "setup-output"
+
+    exit_code = main(
+        [
+            "mcp",
+            "setup",
+            "--repo",
+            str(root),
+            "--import",
+            str(source),
+            "--output",
+            str(output),
+            "--json",
+        ]
+    )
+    payload = json.loads(capsys.readouterr().out)
+    assert exit_code in {0, 1}
+    assert (root / "skills" / "existing-skill" / "SKILL.md").is_file()
+    report = json.loads((output / "import-report.json").read_text(encoding="utf-8"))
+    assert report["import"]["skill_id"] == "existing-skill"
+    assert payload["output"] == str(output.resolve())
+
+
+def test_mcp_setup_defaults_repo_to_current_directory(tmp_path: Path, monkeypatch, capsys) -> None:
+    monkeypatch.chdir(tmp_path)
+    assert main(["mcp", "setup", "--json"]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["ok"] is True
+
+
 def test_mcp_setup_apply_copies_config_and_appends_instructions(tmp_path: Path, capsys) -> None:
     output = tmp_path / "setup-output"
     root = tmp_path / "repo"

{xrefkit-0.4.4 → xrefkit-0.4.5}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.4"
+__version__ = "0.4.5"

xrefkit-0.4.5/xrefkit/mcp/context_token.py

@@ -0,0 +1,108 @@
+"""Signed, client-carried context for stateless MCP requests."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+
+CONTEXT_META_KEY = "io.xrefkit/context_id"
+
+
+@dataclass(frozen=True)
+class ContextClaims:
+    context_id: str
+    repository_fingerprint: str
+    startup_loaded: bool = False
+    client_tools_unlocked: bool = False
+    run_id: str | None = None
+    skill_id: str | None = None
+    mcp_session_id: str | None = None
+    expires_at: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "context_id": self.context_id,
+            "repository_fingerprint": self.repository_fingerprint,
+            "startup_loaded": self.startup_loaded,
+            "client_tools_unlocked": self.client_tools_unlocked,
+            "run_id": self.run_id,
+            "skill_id": self.skill_id,
+            "mcp_session_id": self.mcp_session_id,
+            "expires_at": self.expires_at,
+        }
+
+
+class ContextTokenCodec:
+    def __init__(self, secret: str, repository_fingerprint: str, *, ttl_seconds: int = 3600) -> None:
+        if not secret:
+            raise ValueError("context token secret is required")
+        self._secret = secret.encode("utf-8")
+        self.repository_fingerprint = repository_fingerprint
+        self.ttl_seconds = ttl_seconds
+
+    def issue(
+        self,
+        *,
+        startup_loaded: bool = False,
+        client_tools_unlocked: bool = False,
+        run_id: str | None = None,
+        skill_id: str | None = None,
+        mcp_session_id: str | None = None,
+        context_id: str | None = None,
+    ) -> str:
+        claims = ContextClaims(
+            context_id=context_id or f"xc_{uuid.uuid4().hex}",
+            repository_fingerprint=self.repository_fingerprint,
+            startup_loaded=startup_loaded,
+            client_tools_unlocked=client_tools_unlocked,
+            run_id=run_id,
+            skill_id=skill_id,
+            mcp_session_id=mcp_session_id,
+            expires_at=int(time.time()) + self.ttl_seconds,
+        )
+        body = _encode(claims.to_dict())
+        return f"v1.{body}.{self._signature(body)}"
+
+    def verify(self, token: str) -> ContextClaims:
+        try:
+            version, body, signature = str(token).split(".", 2)
+            if version != "v1" or not hmac.compare_digest(signature, self._signature(body)):
+                raise ValueError("invalid context token signature")
+            payload = json.loads(_decode(body))
+            if payload["repository_fingerprint"] != self.repository_fingerprint:
+                raise ValueError("context token repository mismatch")
+            if int(payload["expires_at"]) < int(time.time()):
+                raise ValueError("context token expired")
+            return ContextClaims(**payload)
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise ValueError("invalid context token") from exc
+
+    def refresh(self, claims: ContextClaims, **updates: Any) -> str:
+        values = claims.to_dict()
+        values.update(updates)
+        values.pop("context_id", None)
+        return self.issue(context_id=claims.context_id, **{k: values[k] for k in (
+            "startup_loaded", "client_tools_unlocked", "run_id", "skill_id", "mcp_session_id"
+        )})
+
+    def _signature(self, body: str) -> str:
+        return _b64(hmac.new(self._secret, body.encode("ascii"), hashlib.sha256).digest())
+
+
+def _b64(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def _encode(value: dict[str, Any]) -> str:
+    return _b64(json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8"))
+
+
+def _decode(value: str) -> str:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)).decode("utf-8")

{xrefkit-0.4.4 → xrefkit-0.4.5}/xrefkit/mcp/server.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 import argparse
 import asyncio
 import logging
+import os
 import sys
+import uuid
 import weakref
 from pathlib import Path
 from typing import Any
@@ -11,6 +13,7 @@ from typing import Any
 from . import __version__
 from .audit import McpAuditLog, SessionRunBinding, SessionRunRegistry
 from .catalog import XRefCatalog
+from .context_token import CONTEXT_META_KEY, ContextClaims, ContextTokenCodec
 from .dist import DIST_ROUTE_PATH, ArtifactDistribution, add_dist_routes
 from xrefkit.structure_catalog import get_entry as get_structure_entry
 from xrefkit.structure_catalog import list_findings as list_structure_findings
@@ -49,6 +52,11 @@ def _mark_startup_loaded(ctx: Any) -> None:
 
 
 def _require_startup_loaded(ctx: Any, tool_name: str) -> None:
+    claims = _context_claims(ctx)
+    if claims is not None:
+        if not claims.startup_loaded:
+            raise RuntimeError(f"XREFKIT_STARTUP_REQUIRED: call get_startup_context before {tool_name}")
+        return
     session = _session_of(ctx)
     if session is not None and session not in _STARTUP_LOADED_SESSIONS:
         raise RuntimeError(
@@ -72,6 +80,7 @@ def _with_control_reminder(result: dict[str, Any]) -> dict[str, Any]:
 # per-Skill flag would make distribution unreachable for Skills that don't
 # declare required_tools even though the general tool catalog still applies.
 _CLIENT_TOOLS_UNLOCKED_SESSIONS: "weakref.WeakSet[Any]" = weakref.WeakSet()
+_CONTEXT_CODEC: ContextTokenCodec | None = None
 
 
 def _unlock_client_tools(ctx: Any) -> None:
@@ -80,7 +89,46 @@ def _unlock_client_tools(ctx: Any) -> None:
         _CLIENT_TOOLS_UNLOCKED_SESSIONS.add(session)
 
 
+def _context_claims(ctx: Any) -> ContextClaims | None:
+    if _CONTEXT_CODEC is None:
+        return None
+    meta = getattr(getattr(ctx, "request_context", None), "meta", None)
+    extra = getattr(meta, "model_extra", None) or (meta if isinstance(meta, dict) else {})
+    token = extra.get(CONTEXT_META_KEY)
+    if token is None:
+        return None
+    try:
+        return _CONTEXT_CODEC.verify(str(token))
+    except ValueError as exc:
+        raise RuntimeError("XREFKIT_CONTEXT_INVALID: context_id could not be verified") from exc
+
+
+def _context_token(claims: ContextClaims | None) -> str | None:
+    if _CONTEXT_CODEC is None or claims is None:
+        return None
+    return _CONTEXT_CODEC.refresh(claims)
+
+
+def _binding_for(ctx: Any, run_registry: SessionRunRegistry) -> SessionRunBinding | None:
+    claims = _context_claims(ctx)
+    if claims is not None and claims.run_id and claims.skill_id and claims.mcp_session_id:
+        return SessionRunBinding(
+            run_id=claims.run_id,
+            mcp_session_id=claims.mcp_session_id,
+            repository_fingerprint=claims.repository_fingerprint,
+            skill_id=claims.skill_id,
+        )
+    return run_registry.current(_session_of(ctx))
+
+
 def _require_client_tools_unlocked(ctx: Any, tool_name: str) -> None:
+    claims = _context_claims(ctx)
+    if claims is not None:
+        if not claims.client_tools_unlocked:
+            raise RuntimeError(
+                f"XREFKIT_SKILL_SELECTION_REQUIRED: call get_skill or get_skill_requirements before {tool_name}"
+            )
+        return
     session = _session_of(ctx)
     if session is not None and session not in _CLIENT_TOOLS_UNLOCKED_SESSIONS:
         raise RuntimeError(
@@ -139,6 +187,15 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="Enable /dist executable artifacts after deployment trust is configured.",
     )
+    parser.add_argument(
+        "--stateless-http",
+        action="store_true",
+        help="Serve Streamable HTTP without MCP protocol sessions; requires XREFKIT_CONTEXT_SECRET.",
+    )
+    parser.add_argument(
+        "--context-secret",
+        help="HMAC secret for client-carried XRefKit context tokens; defaults to XREFKIT_CONTEXT_SECRET.",
+    )
     parser.add_argument(
         "--distribution-trust-id",
         help="Out-of-band pinned release manifest or signing-key identity.",
@@ -156,6 +213,11 @@ def main(argv: list[str] | None = None) -> int:
         help="Structured MCP audit JSONL path. Defaults to <repo>/work/mcp/xid_audit.jsonl.",
     )
     args = parser.parse_args(argv)
+    if args.stateless_http and args.transport != "streamable-http":
+        parser.error("--stateless-http requires --transport streamable-http")
+    context_secret = args.context_secret or os.environ.get("XREFKIT_CONTEXT_SECRET")
+    if args.stateless_http and not context_secret:
+        parser.error("--stateless-http requires --context-secret or XREFKIT_CONTEXT_SECRET")
     try:
         _validate_tls_configuration(
             args.transport,
@@ -177,6 +239,11 @@ def main(argv: list[str] | None = None) -> int:
         parser.error(str(exc))
 
     catalog = XRefCatalog.build(Path(args.repo), args.domain_knowledge_root)
+    global _CONTEXT_CODEC
+    _CONTEXT_CODEC = ContextTokenCodec(
+        context_secret or os.urandom(32).hex(),
+        catalog.repository_fingerprint,
+    )
     audit_log = McpAuditLog(args.audit_log or (Path(args.repo) / "work" / "mcp" / "xid_audit.jsonl"))
     run_registry = SessionRunRegistry()
 
@@ -212,6 +279,7 @@ def main(argv: list[str] | None = None) -> int:
         port=args.port,
         streamable_http_path=args.http_path,
         log_level=args.log_level.upper(),
+        stateless_http=args.stateless_http,
     )
 
     @app.tool()
@@ -221,14 +289,29 @@ def main(argv: list[str] | None = None) -> int:
     @app.tool()
     def bind_skill_run(ctx: Context, run_id: str, skill_id: str) -> dict[str, Any]:
         _require_startup_loaded(ctx, "bind_skill_run")
-        binding = run_registry.bind(
-            _session_of(ctx),
-            run_id=run_id,
-            repository_fingerprint=catalog.repository_fingerprint,
-            skill_id=skill_id,
-        )
+        claims = _context_claims(ctx)
+        if claims is not None:
+            try:
+                normalized_run_id = str(uuid.UUID(str(run_id)))
+            except ValueError as exc:
+                raise ValueError(f"run_id must be a UUID: {run_id}") from exc
+            if claims.run_id and claims.run_id != normalized_run_id:
+                raise ValueError("context_id is already bound to a different Skill Run")
+            binding = SessionRunBinding(
+                run_id=normalized_run_id,
+                mcp_session_id=claims.mcp_session_id or claims.context_id,
+                repository_fingerprint=catalog.repository_fingerprint,
+                skill_id=skill_id,
+            )
+        else:
+            binding = run_registry.bind(
+                _session_of(ctx),
+                run_id=run_id,
+                repository_fingerprint=catalog.repository_fingerprint,
+                skill_id=skill_id,
+            )
         audit_log.append("run.bound", binding=binding, tool="bind_skill_run")
-        return {
+        result = {
             **binding.to_dict(),
             "audit_enabled": True,
             "client_record_command": (
@@ -237,11 +320,26 @@ def main(argv: list[str] | None = None) -> int:
                 f"--repository-fingerprint {binding.repository_fingerprint}"
             ),
         }
+        if claims is not None:
+            result["context_id"] = _CONTEXT_CODEC.refresh(
+                claims,
+                startup_loaded=True,
+                run_id=binding.run_id,
+                skill_id=binding.skill_id,
+                mcp_session_id=binding.mcp_session_id,
+            )
+        return result
 
     @app.tool()
     def end_skill_run(ctx: Context, run_id: str) -> dict[str, str]:
         _require_startup_loaded(ctx, "end_skill_run")
-        binding = run_registry.end(_session_of(ctx), run_id=run_id)
+        claims = _context_claims(ctx)
+        if claims is not None:
+            binding = _binding_for(ctx, run_registry)
+            if binding is None or binding.run_id != run_id:
+                raise ValueError("context_id does not match the active MCP Skill Run binding")
+        else:
+            binding = run_registry.end(_session_of(ctx), run_id=run_id)
         audit_log.append("run.ended", binding=binding, tool="end_skill_run")
         return binding.to_dict()
 
@@ -254,6 +352,12 @@ def main(argv: list[str] | None = None) -> int:
         for xid in result.get("load_order", []):
             _log_xid_query("get_startup_context", xid)
         _mark_startup_loaded(ctx)
+        if _CONTEXT_CODEC is not None:
+            claims = _context_claims(ctx)
+            if claims is None:
+                result["context_id"] = _CONTEXT_CODEC.issue(startup_loaded=True)
+            else:
+                result["context_id"] = _CONTEXT_CODEC.refresh(claims, startup_loaded=True)
         if dist is not None:
             result = _with_artifact_distribution(result, dist, dist_base_url)
         return result
@@ -293,7 +397,7 @@ def main(argv: list[str] | None = None) -> int:
 
     @app.tool()
     def search_knowledge_catalog(ctx: Context, query: str, limit: int = 10) -> list[dict[str, Any]]:
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         result = catalog.search_knowledge_catalog(query, limit)
         if binding is not None:
             audit_log.append(
@@ -309,7 +413,7 @@ def main(argv: list[str] | None = None) -> int:
     @app.tool()
     def get_knowledge_summary(ctx: Context, xid: str) -> dict[str, Any]:
         _require_startup_loaded(ctx, "get_knowledge_summary")
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         result = catalog.expand_knowledge(xid)["entry"]
         _log_xid_query(
             "get_knowledge_summary",
@@ -323,7 +427,7 @@ def main(argv: list[str] | None = None) -> int:
     @app.tool()
     def expand_knowledge(ctx: Context, xid: str) -> dict[str, Any]:
         _require_startup_loaded(ctx, "expand_knowledge")
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         result = catalog.expand_knowledge(xid)
         _log_xid_query(
             "expand_knowledge",
@@ -341,7 +445,7 @@ def main(argv: list[str] | None = None) -> int:
         known_version: str | None = None,
     ) -> dict[str, Any]:
         _require_startup_loaded(ctx, "get_document_by_xid")
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         result = catalog.get_document_by_xid(xid, known_version)
         _log_xid_query(
             "get_document_by_xid",
@@ -357,7 +461,7 @@ def main(argv: list[str] | None = None) -> int:
     @app.tool()
     def build_knowledge_context(ctx: Context, query: str, limit: int = 5) -> dict[str, Any]:
         _require_startup_loaded(ctx, "build_knowledge_context")
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         result = catalog.build_knowledge_context(query, limit)
         if binding is not None:
             audit_log.append(
@@ -403,7 +507,7 @@ def main(argv: list[str] | None = None) -> int:
         known_document_versions: dict[str, str] | None = None,
     ) -> dict[str, Any]:
         _require_startup_loaded(ctx, "get_skill")
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         if binding is not None and binding.skill_id != skill_id:
             raise ValueError(
                 f"get_skill requested {skill_id!r}, but the active Skill Run is bound to {binding.skill_id!r}"
@@ -417,14 +521,30 @@ def main(argv: list[str] | None = None) -> int:
                 selected_skill=skill_id,
             )
         _unlock_client_tools(ctx)
-        return _with_control_reminder(result)
+        response = _with_control_reminder(result)
+        claims = _context_claims(ctx)
+        if claims is not None:
+            response["context_id"] = _CONTEXT_CODEC.refresh(
+                claims,
+                startup_loaded=True,
+                client_tools_unlocked=True,
+            )
+        return response
 
     @app.tool()
     def get_skill_requirements(ctx: Context, skill_id: str) -> dict[str, Any]:
         _require_startup_loaded(ctx, "get_skill_requirements")
         result = catalog.get_skill_requirements(skill_id)
         _unlock_client_tools(ctx)
-        return _with_control_reminder(result)
+        response = _with_control_reminder(result)
+        claims = _context_claims(ctx)
+        if claims is not None:
+            response["context_id"] = _CONTEXT_CODEC.refresh(
+                claims,
+                startup_loaded=True,
+                client_tools_unlocked=True,
+            )
+        return response
 
     @app.tool()
     def resolve_skill_knowledge(ctx: Context, skill_id: str) -> dict[str, Any]:
@@ -433,7 +553,7 @@ def main(argv: list[str] | None = None) -> int:
 
     @app.tool()
     def rank_skills_for_purpose(ctx: Context, purpose: str, limit: int = 5) -> list[dict[str, Any]]:
-        binding = run_registry.current(_session_of(ctx))
+        binding = _binding_for(ctx, run_registry)
         result = catalog.rank_skills_for_purpose(purpose, limit)
         if binding is not None:
             audit_log.append(

{xrefkit-0.4.4 → xrefkit-0.4.5}/xrefkit/mcp/setup.py

@@ -135,7 +135,7 @@ def setup(args: argparse.Namespace) -> int:
     metas: list[Path] = []
 
     if args.import_source:
-        from xrefkit.import_skill import convert_skill, convert_skill_tree
+        from xrefkit.import_skill import _find_skill_doc, _slug, convert_skill, convert_skill_tree
 
         source = Path(args.import_source).resolve()
         if (source / "skills").is_dir() or args.batch:
@@ -148,14 +148,20 @@ def setup(args: argparse.Namespace) -> int:
             )
             import_report = result.to_dict()
         else:
-            if not args.skill_id:
-                raise SystemExit("--skill-id is required when --import is a single Skill directory")
+            try:
+                _find_skill_doc(source, None)
+            except FileNotFoundError as exc:
+                raise SystemExit(
+                    "--import must point to a Skill directory containing SKILL.md or README.md, "
+                    "or a directory containing skills/"
+                ) from exc
+            skill_id = args.skill_id or _slug(source.name)
             result = convert_skill(
                 source_dir=source,
                 source_root=source.parent,
                 repo_root=root,
-                skill_id=args.skill_id,
-                target_skill_dir=root / "skills" / args.skill_id,
+                skill_id=skill_id,
+                target_skill_dir=root / "skills" / skill_id,
                 dry_run=False,
             )
             import_report = result.to_dict()
@@ -211,7 +217,7 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="xrefkit mcp")
     sub = parser.add_subparsers(dest="command", required=True)
     setup_parser = sub.add_parser("setup", help="import Skills and generate reviewable MCP setup artifacts")
-    setup_parser.add_argument("--repo", required=True)
+    setup_parser.add_argument("--repo", default=".", help="Target XRefKit repository; defaults to the current directory")
     setup_parser.add_argument("--import", dest="import_source", default=None, help="Skill directory or batch root")
     setup_parser.add_argument("--batch", action="store_true")
     setup_parser.add_argument("--skill-id-prefix", default="imported")
@@ -232,3 +238,4 @@ def main(argv: list[str] | None = None) -> int:
 
 if __name__ == "__main__":
     raise SystemExit(main())
+

{xrefkit-0.4.4 → xrefkit-0.4.5}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.4
+Version: 0.4.5
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -101,6 +101,38 @@ and handoff records from collapsing into one opaque instruction block.
 
 ![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
 
+## Skills: what you can ask XRefKit to do
+
+XRefKit includes Skills for common stages of software and business work. For
+example:
+
+- **Business discovery and planning**: `business_learning_interview`,
+  `business_intake_scoping`, `requirements_flow`, `planning_flow`, and
+  `estimation_flow`
+- **Investigation, design, and implementation**: `investigation_flow`,
+  `source_structure_overview`, `db_current_state_analysis`, `db_design`,
+  `design_flow`, and `implementation_flow`
+- **Constraint and change analysis**: `constraint_derivation_index`,
+  `dotnet_change_analysis`, `code_constraint_derivation`,
+  `cross_constraint_derivation`, and `integration_scenario_derivation`
+- **Review and quality**: `csharp_review`, `python_review`, `security_review`,
+  `test_flow`, `qa_gate_review`, and `review_report_composition`
+- **Knowledge and Skill operations**: `import_skill`, `skill_flow_authoring`,
+  `knowledge_ontology_management`, `judgment_log`, `doc_ship`, and
+  `skill_calibration_evaluation`
+- **Documents and communication**: `pptx_spec_traceability`,
+  `xlsx_spec_traceability`, `presentation_flow_review`, `editorial_intake`,
+  `draft_authoring`, and `marketing_slide_png`
+
+Each Skill is a reusable procedure with a capability/tuning/responsibility
+identity. Its procedure, routing metadata, domain Knowledge, and run evidence
+remain separate. Describe your goal in natural language and XRefKit routes it
+to the relevant Skill; the [Skill catalog](skills/_index.md#xid-8D91F66DDBB7)
+contains the complete current list and summaries.
+
+To install and enable Skills distributed as Python Packages, follow the
+[package-first registration guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+
 ## How It Works
 
 1. Original materials are kept in `sources/`.
@@ -196,6 +228,18 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+For a network deployment without MCP protocol sessions, provide a shared HMAC
+secret and enable stateless HTTP. The client must return the `context_id` from
+`get_startup_context` in `_meta.io.xrefkit/context_id` on later requests:
+
+```powershell
+$env:XREFKIT_CONTEXT_SECRET = 'replace-with-a-managed-secret'
+python -m xrefkit.mcp.server --repo . --transport streamable-http --stateless-http
+```
+
+The context token is signed, repository-bound, and short-lived. It is an
+execution-context token, not a canonical XID or an authorization grant.
+
 ## Skill Run Observation Dashboard
 
 The local dashboard lets a human inspect Skill run status, closure and quality

{xrefkit-0.4.4 → xrefkit-0.4.5}/xrefkit.egg-info/SOURCES.txt

@@ -79,6 +79,7 @@ xrefkit/mcp/catalog.py
 xrefkit/mcp/cli.py
 xrefkit/mcp/client_cache.py
 xrefkit/mcp/context_registry.py
+xrefkit/mcp/context_token.py
 xrefkit/mcp/contracts.py
 xrefkit/mcp/dist.py
 xrefkit/mcp/ownership.py