@topy-ai/maggie 0.7.46 → 0.7.47

package/README-zh-TW.md

@@ -29,9 +29,17 @@ npx @topy-ai/maggie init --scope project --agent all
 npx @topy-ai/maggie doctor --scope project --project .
 ```
 
-目前 release 是 `0.7.46`。新增 browser adapter capability preflight、privacy-safe
-feedback evidence references/relationships、bounded batch-review evidence graph、
-remediation suggestions，以及 root-level unittest import 支援。`browser-audit
+目前 release 是 `0.7.47`。本版處理 2026-09-26 五條新 feedback：project-scope
+`maggie init` 會建立本地 memory store；context 預設只讀取本 project scope；memory hook
+在 local Python adapter 不存在時 fallback 到已安裝 CLI；重複 init 保留既有檔案與時間戳；
+`maggie feedback list` 的 `--project` 可放在子命令前或後。Generated VPS runner 現在記錄
+Maggie 版本與 template fingerprint；preflight 會警示過期/無標記 runner，其他路徑可用
+`maggie deployment --check-runner PATH` 檢查。
+
+0.7.46 feedback batch 仍包含 release profile capability gate、deployment readiness bounded
+retry、Google account/property target verification、GA/GTM external-write idempotency/readback、
+browser adapter capability preflight、privacy-safe feedback evidence references/relationships，
+以及 root-level unittest import 支援。`browser-audit
 --check-browser` 會在導覽前拒絕 missing/incompatible adapter，包括解析成
 `xdg-open` 的系統 `browse`；feedback graph 不保存 raw payload、logs、credentials
 或本機路徑。另包含 0.7.45 的 Codex/Claude Code 一次性 user-scope 安裝、bundled
@@ -105,7 +113,7 @@ structure drift 或重複 treatment product 時 fail closed。
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 source tree 的正式 release 是 `0.7.46`。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
+目前 source tree 的正式 release 是 `0.7.47`。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
 dispatch、`maggie --version`、feedback batch review 聚合與重複偵測、marketplace enrichment evidence、booking
 worker/resolver evidence，以及 read-only migration preflight。它也包含 host-owned mobile app surface contract、signed-in
 camera-state QA、直接 Astro route resolution、correlated feedback batch，以及

package/README.md

@@ -89,10 +89,20 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 20 installable skills and a local-first MaggieDash foundation.
 
-The current release is `0.7.46`. It adds browser-adapter capability preflight,
-privacy-safe feedback evidence references/relationships, bounded batch-review
-evidence graphs, remediation suggestions, and root-level unittest import
-support. `browser-audit --check-browser` rejects missing or incompatible
+The current release is `0.7.47`. Project initialization creates a local Maggie
+Memory store, memory contexts default to project scope, and the shared hook
+falls back to the installed CLI if project Python tools are absent. Repeated
+memory initialization preserves existing files and timestamps. Feedback list
+accepts `--project` before or after its subcommand. Generated VPS runners record
+their Maggie version and template fingerprint; deployment preflight warns on
+stale or unmarked runners, with `maggie deployment --check-runner PATH` for
+other locations.
+
+The 0.7.46 feedback batch remains included: capability-aware release profiles,
+bounded deployment-readiness retries, verified Google account/target evidence,
+idempotent external-write readback, browser-adapter capability preflight,
+privacy-safe feedback evidence and relationships, and root-level unittest
+import support. `browser-audit --check-browser` rejects missing or incompatible
 adapters before navigation, including a system `browse`/`xdg-open` opener.
 It also includes the 0.7.45 one-time user-scope installation for
 Codex and Claude Code, a bundled workflow runner, and scoped maintenance
@@ -657,8 +667,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.46 update --scope project --project . --force
-npx @topy-ai/maggie@0.7.46 cleanup --scope project --project .
+npx @topy-ai/maggie@0.7.47 update --scope project --project . --force
+npx @topy-ai/maggie@0.7.47 cleanup --scope project --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never

package/bin/maggie.js

@@ -19,6 +19,23 @@ const TEMPLATES_ROOT = join(PACKAGE_ROOT, "bundled-templates");
 const STATE_DIR = ".maggie";
 const USER_SCOPE = "user";
 const PROJECT_SCOPE = "project";
+const PROJECT_MEMORY_FILES = {
+  preferences: "preferences.json",
+  conventions: "project-conventions.json",
+  lessons: "lessons.json",
+  errors: "error-patterns.json",
+};
+
+function initializeProjectMemory(root) {
+  const memoryRoot = join(root, STATE_DIR, "memory");
+  mkdirSync(memoryRoot, { recursive: true });
+  for (const [kind, filename] of Object.entries(PROJECT_MEMORY_FILES)) {
+    const path = join(memoryRoot, filename);
+    if (!existsSync(path)) {
+      writeFileSync(path, `${JSON.stringify({ schemaVersion: 1, kind, updatedAt: new Date().toISOString(), items: [] }, null, 2)}\n`, { flag: "wx" });
+    }
+  }
+}
 function loadSkillNames() {
   try {
     return JSON.parse(readFileSync(join(SKILLS_ROOT, "catalog.json"), "utf8")).skills.map((skill) => skill.name);
@@ -488,6 +505,7 @@ function install(args) {
     if (existsSync(MARKETPLACE_ROOT)) copyIfMissing(MARKETPLACE_ROOT, join(root, "marketplace"));
     if (existsSync(CONTRACTS_ROOT)) copyIfMissing(CONTRACTS_ROOT, join(root, "contracts"));
     if (existsSync(join(TEMPLATES_ROOT, "maggiedash"))) copyIfMissing(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"));
+    initializeProjectMemory(root);
   }
   const manifestRoots = scope === USER_SCOPE ? allUserAgentRoots() : roots;
   const installedUserSkills = scope === USER_SCOPE ? mergedUserSkillNames(manifestRoots) : [];
@@ -496,7 +514,7 @@ function install(args) {
     : { scope, version: PACKAGE_VERSION, agents: roots.map((item) => item.slice(root.length + 1)), skills: mergedSkillNames(root, skills), managedFiles: managedFileDigests(root, roots, skills), installed_at: new Date().toISOString() };
   writeInstallManifest(root, manifest, scope);
   console.log(scope === USER_SCOPE ? `Maggie installed for this user in ${userStateRoot()}` : `Maggie installed in ${root}`);
-  console.log(scope === USER_SCOPE ? "Project state remains local; run `maggie doctor --scope user` to verify the user install." : "Run `maggie doctor --project .` before using mutating workflows.");
+  console.log(scope === USER_SCOPE ? "Project state remains local; run `maggie doctor --scope user` to verify the user install." : "Project-scoped Maggie Memory is initialized locally; run `maggie doctor --project .` before using mutating workflows.");
 }
 
 function update(args) {
@@ -591,7 +609,7 @@ function workflowCli(name, args) {
   const root = projectRoot(args);
   const script = toolScript(name, root);
   if (!existsSync(script)) throw new Error(`${name} is missing: ${script}`);
-  const env = name === "maggie_feedback.py" ? { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION } : process.env;
+  const env = { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION };
   const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root, env });
   if (result.error) throw result.error;
   process.exitCode = result.status ?? 1;

package/bundled-references/memory-hook.md

@@ -1,23 +1,36 @@
 # Maggie Memory Hook
 
-Every Maggie skill invocation has an automatic memory lifecycle when the host
-project contains `tools/clis/maggie_memory.py`.
+Every Maggie skill invocation uses the current project's Maggie Memory by
+default. Project initialization creates `.maggie/memory/` for that repository.
 
 ## Before work
 
-Run:
+Use the project-local adapter when it is present:
 
 ```bash
 python3 tools/clis/maggie_memory.py context --project . --skill <current-skill>
 ```
 
+If that adapter is absent, use the installed CLI:
+
+```bash
+maggie memory context --project . --skill <current-skill>
+```
+
 Load the returned active preferences, conventions, lessons, and matching error
 history into the current decision context. Surface material rules and verify
 them against current project evidence. Memory never replaces inspection,
 approval, bootstrap, or production gates.
 
-If the command is unavailable, report that memory is unavailable and continue
-with the normal workflow. Do not invent or silently reconstruct memory.
+The context response reports `status: "uninitialized"` when Maggie Memory is
+available but the project has not initialized its store. In that case, explain
+that `maggie init --scope project` initializes it; do not call memory
+unavailable. Report unavailable only when neither the project adapter nor the
+installed `maggie` CLI can run. Do not invent or silently reconstruct memory.
+
+Context includes only active project-scope items for the current repository.
+Include user/workspace entries only after a separate explicit opt-in with
+`--include-shared`.
 
 ## After work
 

package/bundled-skills/maggie-deployment/SKILL.md

@@ -219,6 +219,12 @@ files and the application remain separated (`maggie-deploy` versus
 Install and review that narrow sudoers policy on the host before executing a
 runner.
 
+Generated release runners include their Maggie version and a template
+fingerprint. VPS preflight checks runners under `.maggie/deployment/` and warns
+when they are unmarked or stale; use `--check-runner PATH` for a runner stored
+elsewhere. Regenerate from the reviewed VPS plan, inspect the diff, and replace
+the checked-in runner only after review.
+
 VPS plans include a bounded retention policy: keep two immutable releases,
 preserve the `current` target and rollback target, and review prune candidates
 before any operator executes cleanup. Generate a read-only candidate report:

package/bundled-skills/maggie-feedback/SKILL.md

@@ -30,7 +30,9 @@ maggie feedback --project . collect \
 maggie feedback preview .maggie/feedback/<feedback-id>.json --format markdown
 ```
 
-The draft is written to `.maggie/feedback/`. It contains the Maggie version,
+The draft is written to `.maggie/feedback/`. List local drafts with
+`maggie feedback list --project .`; `--project` works before or after the
+subcommand. A draft contains the Maggie version,
 skill, run ID, phase, error fingerprint, expected/actual result, reproduction
 steps, resolution, validation, and metadata-only screenshot references.
 

package/bundled-skills/maggie-memory/SKILL.md

@@ -29,7 +29,7 @@ truth, content state, or audit log.
 
 ## Workflow
 
-1. At the start of a relevant workflow, run `maggie memory context --project . --skill <skill>` and load only matching active items.
+1. At the start of a relevant workflow, run `maggie memory context --project . --skill <skill>` and load only matching active project-scope items. Use `--include-shared` only after explicit opt-in.
 2. Show material preferences, conventions, and prevention lessons before making a decision.
 3. When the user gives a durable preference or confirms a repaired pitfall, save it explicitly as `candidate` or `active` with scope and evidence.
 4. Record every meaningful failure with `record-error`; include a stable fingerprint, resolution, and validation result when fixed.
@@ -45,6 +45,15 @@ truth, content state, or audit log.
 preserving project scope. Expired active items remain inspectable through
 explicit status listing but are excluded from normal context.
 
+Project-scope `maggie init` creates the repository's `.maggie/memory/` store.
+Repeated initialization preserves existing memory files without rewriting
+their contents or timestamps. A context response distinguishes a ready store
+from an uninitialized project; the shared memory hook falls back to the
+installed CLI when local Python tools are absent.
+
+Project `context`, `search`, and `list` read only project-scope items by
+default. `--include-shared` explicitly opts into user/workspace-scoped entries.
+
 ```bash
 maggie memory init --project .
 maggie memory context --project . --skill maggie-clone

package/bundled-tools/clis/maggie_deployment.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
+import inspect
 import json
+import os
 import re
 import shlex
 import subprocess
@@ -352,6 +355,9 @@ def preflight(
         result["delegation"] = delegation
         result["vps"] = {"runtime":"Node.js standalone","reverseProxy":"Nginx","processManager":"systemd","releaseLayout":"/var/www/<site>/releases/<release> + current symlink","dns":"Cloudflare DNS or registrar DNS; verify apex and www separately","remoteCommands":["npm ci","npm run build","systemctl restart <service>","systemctl is-active <service>","curl -fsS https://<domain>/robots.txt","curl -fsS https://<domain>/sitemap.xml"],"handoverFields":["host","sshUser","domain","service","release","previousRelease","nginxConfig","migrationVersion","verification","rollback"]}
         result["next_action"] = "review VPS host, SSH user, domain/DNS, systemd service, Nginx config, release path, migrations, and rollback owner before execute"
+        runners = sorted(deployment_dir.rglob("release-runner.sh")) if deployment_dir.exists() else []
+        result["release_runners"] = [release_runner_status(path) for path in runners[:25]]
+        result["warnings"] = [f"generated release runner is stale or unmarked: {item['path']}" for item in result["release_runners"] if item["status"] == "stale"]
         result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
         if require_deployer:
             result["blocking_checks"].append("deployer_delegation")
@@ -549,15 +555,51 @@ WantedBy=multi-user.target
     (output_dir / f"{domain}.conf").write_text(nginx, encoding="utf-8")
 
 
+def release_runner_generator() -> dict[str, str]:
+    version = os.environ.get("MAGGIE_VERSION", "").strip()
+    if not version:
+        version_file = Path(__file__).resolve().parents[2] / "VERSION"
+        try:
+            version = version_file.read_text(encoding="utf-8").strip()
+        except OSError:
+            version = "unknown"
+    source = inspect.getsource(release_runner).encode("utf-8")
+    return {"version": version, "fingerprint": hashlib.sha256(source).hexdigest()[:16]}
+
+
+def release_runner_status(path: Path) -> dict:
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as error:
+        return {"path": str(path), "status": "stale", "reason": f"runner cannot be read: {error}", "refresh": "Regenerate from the reviewed VPS plan and inspect the diff."}
+    match = re.search(r"^# Maggie release runner: generator=([^ ]+) template=([a-f0-9]{16})$", content, re.MULTILINE)
+    current = release_runner_generator()
+    if not match:
+        return {"path": str(path), "status": "stale", "reason": "runner has no generator version/fingerprint", "currentGenerator": current, "refresh": "Regenerate from the reviewed VPS plan and inspect the diff before replacing this file."}
+    generated = {"version": match.group(1), "fingerprint": match.group(2)}
+    stale = generated != current
+    return {
+        "path": str(path),
+        "status": "stale" if stale else "current",
+        "generatedBy": generated,
+        "currentGenerator": current,
+        "reason": "runner generator version or template fingerprint has changed" if stale else "runner matches the current generator",
+        "refresh": "Regenerate from the reviewed VPS plan and inspect the diff before replacing this file." if stale else "",
+    }
+
+
 def release_runner(plan: dict) -> str:
     """Render the ordered, reviewable VPS runner for one release."""
     root = plan["release_root"]
     service = plan["service"]
     domain = plan["domain"]
     current = plan["current_release"]
+    generator = release_runner_generator()
     return f'''#!/usr/bin/env bash
 set -euo pipefail
 
+# Maggie release runner: generator={generator["version"]} template={generator["fingerprint"]}
+
 # Migration precedes the symlink flip; later releases carry agent state.
 : "${{RELEASE_ID:?set RELEASE_ID to an immutable release name}}"
 RELEASE_KIND="${{RELEASE_KIND:-upgrade}}"
@@ -653,6 +695,7 @@ def main() -> int:
     parser.add_argument("--deployer-evidence", help="delegation evidence JSON; defaults to .maggie/deployment/deployer-delegation.json")
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
     parser.add_argument("--runner-output", help="write a reviewable ordered VPS release runner")
+    parser.add_argument("--check-runner", help="read-only check of a generated runner's Maggie version and template fingerprint")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
     parser.add_argument("--current-link", help="current symlink for --retention-plan")
     parser.add_argument("--keep-releases", type=int, default=2)
@@ -665,6 +708,10 @@ def main() -> int:
     parser.add_argument("--has-auth", action="store_true")
     args = parser.parse_args()
     try:
+        if args.check_runner:
+            report = release_runner_status(Path(args.check_runner).expanduser().resolve())
+            print(json.dumps(report, indent=2, ensure_ascii=False))
+            return 0
         if args.verify_deployer:
             if not args.deployer_host:
                 parser.error("--deployer-host is required with --verify-deployer")

package/bundled-tools/clis/maggie_feedback.py

@@ -575,6 +575,7 @@ def main() -> int:
     submit_parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
     submit_parser.add_argument("--confirm", action="store_true")
     list_parser = sub.add_parser("list")
+    list_parser.add_argument("--project", default=argparse.SUPPRESS)
     args = parser.parse_args()
     try:
         if args.command == "collect": return collect(args)

package/bundled-tools/clis/maggie_memory.py

@@ -35,12 +35,15 @@ def main() -> int:
     listing.add_argument("--status", choices=sorted(memory.STATUSES), default=None)
     listing.add_argument("--skill", default="")
     listing.add_argument("--query", default="")
+    listing.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     search = add_project(sub.add_parser("search"))
     search.add_argument("query")
     search.add_argument("--skill", default="")
+    search.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     context = add_project(sub.add_parser("context"))
     context.add_argument("--skill", default="")
     context.add_argument("--query", default="")
+    context.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     add = add_project(sub.add_parser("add"))
     add.add_argument("kind", choices=("preferences", "conventions", "lessons"))
     add.add_argument("--scope", choices=sorted(memory.SCOPES), required=True)
@@ -85,17 +88,21 @@ def main() -> int:
             output(memory.transition(args.project, args.kind, args.item_id, args.status))
         elif args.command in {"context", "search", "list"}:
             query = args.query if args.command == "search" else getattr(args, "query", "")
-            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None))
+            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None), include_shared=getattr(args, "include_shared", False))
             if args.command == "list" and args.kind:
                 result = {args.kind: result[args.kind]}
             if args.command == "list" and args.status:
                 result = {kind: [item for item in items if item.get("status") == args.status] for kind, items in result.items()}
-            output(result)
+            if args.command == "context":
+                ready = memory.initialized(args.project)
+                output({"status": "ready" if ready else "uninitialized", "initialized": ready, **result})
+            else:
+                output(result)
         elif args.command == "export":
             payload = {kind: memory.read(args.project, kind) for kind in memory.KINDS if kind != "errors"}
             if args.public_safe:
                 for value in payload.values():
-                    value["items"] = [item for item in value["items"] if item.get("scope") != "user" and item.get("status") == "active"]
+                    value["items"] = [item for item in value["items"] if item.get("scope") == "project" and item.get("status") == "active"]
             destination = Path(args.output)
             destination.parent.mkdir(parents=True, exist_ok=True)
             destination.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")

package/bundled-tools/runtime/maggie_memory.py

@@ -73,7 +73,16 @@ def write(project: str | Path, kind: str, payload: dict[str, Any]) -> Path:
 
 
 def init(project: str | Path) -> dict[str, str]:
-    return {kind: str(write(project, kind, read(project, kind))) for kind in KINDS}
+    paths: dict[str, str] = {}
+    for kind in KINDS:
+        path = memory_path(project, kind)
+        if path.exists():
+            # Validate existing state, but keep its bytes and mtime unchanged.
+            read(project, kind)
+        else:
+            write(project, kind, empty(kind))
+        paths[kind] = str(path)
+    return paths
 
 
 def _text(value: Any, field: str, required: bool = False) -> str:
@@ -176,11 +185,13 @@ def _active(item: dict[str, Any], project_id: str = "") -> bool:
     return not expires or expires > now()
 
 
-def relevant(project: str | Path, *, skill: str = "", query: str = "", project_id: str = "", status: str | None = None) -> dict[str, list[dict[str, Any]]]:
+def relevant(project: str | Path, *, skill: str = "", query: str = "", project_id: str = "", status: str | None = None, include_shared: bool = False) -> dict[str, list[dict[str, Any]]]:
     terms = set(re.findall(r"[a-z0-9_-]+", f"{skill} {query}".lower()))
     result: dict[str, list[dict[str, Any]]] = {kind: [] for kind in KINDS}
     for kind in KINDS:
         for item in read(project, kind)["items"]:
+            if not include_shared and item.get("scope") != "project":
+                continue
             if status is not None:
                 if item.get("status") != status:
                     continue
@@ -194,6 +205,10 @@ def relevant(project: str | Path, *, skill: str = "", query: str = "", project_i
     return result
 
 
+def initialized(project: str | Path) -> bool:
+    return all(memory_path(project, kind).is_file() for kind in KINDS)
+
+
 def transition(project: str | Path, kind: str, item_id: str, status: str) -> dict[str, Any]:
     if status not in STATUSES:
         raise ValueError(f"invalid status: {status}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.46",
+  "version": "0.7.47",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/memory-hook.md

@@ -1,23 +1,36 @@
 # Maggie Memory Hook
 
-Every Maggie skill invocation has an automatic memory lifecycle when the host
-project contains `tools/clis/maggie_memory.py`.
+Every Maggie skill invocation uses the current project's Maggie Memory by
+default. Project initialization creates `.maggie/memory/` for that repository.
 
 ## Before work
 
-Run:
+Use the project-local adapter when it is present:
 
 ```bash
 python3 tools/clis/maggie_memory.py context --project . --skill <current-skill>
 ```
 
+If that adapter is absent, use the installed CLI:
+
+```bash
+maggie memory context --project . --skill <current-skill>
+```
+
 Load the returned active preferences, conventions, lessons, and matching error
 history into the current decision context. Surface material rules and verify
 them against current project evidence. Memory never replaces inspection,
 approval, bootstrap, or production gates.
 
-If the command is unavailable, report that memory is unavailable and continue
-with the normal workflow. Do not invent or silently reconstruct memory.
+The context response reports `status: "uninitialized"` when Maggie Memory is
+available but the project has not initialized its store. In that case, explain
+that `maggie init --scope project` initializes it; do not call memory
+unavailable. Report unavailable only when neither the project adapter nor the
+installed `maggie` CLI can run. Do not invent or silently reconstruct memory.
+
+Context includes only active project-scope items for the current repository.
+Include user/workspace entries only after a separate explicit opt-in with
+`--include-shared`.
 
 ## After work