@jetrabbits/agentic 0.0.4 → 0.0.5

package/agentic

@@ -11,6 +11,8 @@ APP_NAME="agentic"
 APP_TITLE="Agentic Installer"
 APP_TUI_TITLE="Agentic installer (TUI mode)"
 APP_REPO_URL="https://github.com/sawrus/agent-guides.git"
+APP_REPO_LINK="https://github.com/sawrus/agent-guides"
+PROJECT_MANIFEST_NAME=".agentic.json"
 
 DEFAULT_AGENT_OS="default"
 STATIC_AGENT_OS=(default opencode codex claude antigravity cursor agents)
@@ -21,6 +23,7 @@ XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
 XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
 APP_CONFIG_DIR="$XDG_CONFIG_HOME/$APP_NAME"
 APP_CONFIG_FILE="$APP_CONFIG_DIR/config"
+OPENCODE_PLUGIN_CONFIG_FILE="$APP_CONFIG_DIR/opencode-plugins.json"
 APP_DATA_DIR="$XDG_DATA_HOME/$APP_NAME"
 APP_REPO_DIR="$APP_DATA_DIR/repo"
 
@@ -47,8 +50,12 @@ SELF_INSTALL_WITH_FZF=false
 
 CREATED_PATHS=()
 COPIED_PATHS=()
+MANAGED_RECORDS=()
+SKIPPED_MANAGED_PATHS=()
 WARNINGS=()
 
+CONTEXT7_API_KEY="${CONTEXT7_API_KEY:-}"
+
 COLOR_RESET=""
 COLOR_HEADER=""
 COLOR_INFO=""
@@ -505,6 +512,390 @@ ensure_dir() {
   unique_append "$path" CREATED_PATHS
 }
 
+ensure_python_available() {
+  if ! command -v python3 >/dev/null 2>&1; then
+    error "python3 is required for managed install metadata and generated markers"
+    exit 1
+  fi
+}
+
+selected_agent_os_contains() {
+  local expected="$1"
+  local agent
+  for agent in "${SELECTED_AGENT_OS[@]}"; do
+    if [[ "$agent" == "$expected" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+project_manifest_path() {
+  printf '%s\n' "$PROJECT_DIR/$PROJECT_MANIFEST_NAME"
+}
+
+project_rel_path() {
+  local path="$1"
+  local rel="${path#"$PROJECT_DIR"/}"
+  printf '%s\n' "$rel"
+}
+
+hash_file() {
+  local path="$1"
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$path" | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$path" | awk '{print $1}'
+  else
+    error "shasum or sha256sum is required to track managed files"
+    exit 1
+  fi
+}
+
+manifest_has_path() {
+  local rel="$1"
+  local manifest
+  manifest="$(project_manifest_path)"
+  [[ -f "$manifest" ]] || return 1
+  python3 - "$manifest" "$rel" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+manifest = Path(sys.argv[1])
+rel = sys.argv[2]
+try:
+    data = json.loads(manifest.read_text(encoding="utf-8"))
+except Exception:
+    sys.exit(1)
+for item in data.get("managed_files", []):
+    if item.get("path") == rel:
+        sys.exit(0)
+sys.exit(1)
+PY
+}
+
+manifest_hash_for_path() {
+  local rel="$1"
+  local manifest
+  manifest="$(project_manifest_path)"
+  [[ -f "$manifest" ]] || return 0
+  python3 - "$manifest" "$rel" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+manifest = Path(sys.argv[1])
+rel = sys.argv[2]
+try:
+    data = json.loads(manifest.read_text(encoding="utf-8"))
+except Exception:
+    sys.exit(0)
+for item in data.get("managed_files", []):
+    if item.get("path") == rel:
+        print(item.get("content_hash", ""))
+        break
+PY
+}
+
+can_write_managed_file() {
+  local dest="$1"
+  local rel
+  rel="$(project_rel_path "$dest")"
+
+  if [[ -f "$(project_manifest_path)" ]]; then
+    if ! manifest_has_path "$rel"; then
+      if [[ -e "$dest" ]]; then
+        warn "Skipping unmanaged target on rerun: $rel"
+        unique_append "$rel" SKIPPED_MANAGED_PATHS
+        return 1
+      fi
+      return 0
+    fi
+
+    if [[ -f "$dest" ]]; then
+      local expected_hash current_hash
+      expected_hash="$(manifest_hash_for_path "$rel")"
+      if [[ -n "$expected_hash" ]]; then
+        current_hash="$(hash_file "$dest")"
+        if [[ "$current_hash" != "$expected_hash" ]]; then
+          warn "Skipping user-modified managed file: $rel"
+          unique_append "$rel" SKIPPED_MANAGED_PATHS
+          return 1
+        fi
+      fi
+    fi
+  fi
+
+  return 0
+}
+
+register_managed_file() {
+  local dest="$1"
+  local source_ref="$2"
+  local marker="$3"
+  local rel
+  rel="$(project_rel_path "$dest")"
+  local digest
+  digest="$(hash_file "$dest")"
+  MANAGED_RECORDS+=("$rel|$source_ref|$digest|$marker")
+  unique_append "$dest" COPIED_PATHS
+}
+
+record_agentic_event() {
+  local kind="$1"
+  local value="${2:-}"
+
+  case "$kind" in
+    DIR)
+      unique_append "$value" CREATED_PATHS
+      ;;
+    COPIED)
+      unique_append "$value" COPIED_PATHS
+      ;;
+    RECORD)
+      MANAGED_RECORDS+=("$value")
+      ;;
+    SKIP)
+      unique_append "$value" SKIPPED_MANAGED_PATHS
+      ;;
+    WARN)
+      warn "$value"
+      ;;
+  esac
+}
+
+write_file_with_agentic_marker() {
+  local src="$1"
+  local dest="$2"
+  local source_ref="$3"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN write managed file $dest"
+    unique_append "$dest" COPIED_PATHS
+    return
+  fi
+
+  can_write_managed_file "$dest" || return 0
+
+  ensure_dir "$(dirname -- "$dest")"
+  python3 - "$src" "$dest" "$source_ref" "$APP_REPO_LINK" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+src = Path(sys.argv[1])
+dest = Path(sys.argv[2])
+source_ref = sys.argv[3]
+repo = sys.argv[4]
+text = src.read_text(encoding="utf-8")
+suffix = dest.suffix.lower()
+marker = f"Generated by agentic; source: {source_ref}; repository: {repo}"
+
+
+def yaml_quote(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def markdown_with_marker(body: str) -> str:
+    block = (
+        "agentic:\n"
+        "  generated_by: agentic\n"
+        f"  source: {yaml_quote(source_ref)}\n"
+        f"  repository: {yaml_quote(repo)}\n"
+    )
+    if body.startswith("---\n"):
+        end = body.find("\n---", 4)
+        if end != -1:
+            return body[: end + 1] + block + body[end + 1 :]
+    return (
+        "---\n"
+        + block
+        + "---\n"
+        + body
+    )
+
+
+def commented(body: str, prefix: str) -> str:
+    line = f"{prefix} {marker}\n"
+    if body.startswith("#!"):
+        first, sep, rest = body.partition("\n")
+        if sep:
+            return first + sep + line + rest
+    return line + body
+
+
+if suffix == ".md":
+    output = markdown_with_marker(text)
+elif suffix == ".json":
+    data = json.loads(text)
+    if not isinstance(data, dict):
+        raise SystemExit(f"Cannot add agentic metadata to non-object JSON: {dest}")
+    data["_agentic"] = {
+        "generated_by": "agentic",
+        "source": source_ref,
+        "repository": repo,
+    }
+    output = json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+elif suffix in {".ts", ".tsx", ".js", ".jsx", ".css"}:
+    output = commented(text, "//")
+elif suffix in {".sh", ".toml", ".py", ".yml", ".yaml"}:
+    output = commented(text, "#")
+else:
+    output = commented(text, "#")
+
+dest.write_text(output, encoding="utf-8")
+PY
+  register_managed_file "$dest" "$source_ref" "internal"
+}
+
+write_agentic_manifest() {
+  local project_dir="$1"
+  local manifest="$project_dir/$PROJECT_MANIFEST_NAME"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN write $manifest"
+    return
+  fi
+
+  local records_file skipped_file
+  records_file="$(mktemp "${TMPDIR:-/tmp}/agentic-records.XXXXXX")"
+  skipped_file="$(mktemp "${TMPDIR:-/tmp}/agentic-skipped.XXXXXX")"
+  if [[ "${#MANAGED_RECORDS[@]}" -gt 0 ]]; then
+    printf '%s\n' "${MANAGED_RECORDS[@]}" > "$records_file"
+  else
+    : > "$records_file"
+  fi
+  if [[ "${#SKIPPED_MANAGED_PATHS[@]}" -gt 0 ]]; then
+    printf '%s\n' "${SKIPPED_MANAGED_PATHS[@]}" > "$skipped_file"
+  else
+    : > "$skipped_file"
+  fi
+
+  local agent_os_csv areas_csv specs_csv
+  local old_ifs="$IFS"
+  IFS=,
+  agent_os_csv="${SELECTED_AGENT_OS[*]}"
+  areas_csv="${SELECTED_AREAS[*]}"
+  specs_csv="${SELECTED_SPECS[*]}"
+  IFS="$old_ifs"
+
+  python3 - "$manifest" "$records_file" "$skipped_file" "$APP_REPO_LINK" "$REPO_ROOT" "$agent_os_csv" "$areas_csv" "$specs_csv" <<'PY'
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+manifest = Path(sys.argv[1])
+records_file = Path(sys.argv[2])
+skipped_file = Path(sys.argv[3])
+repo_link = sys.argv[4]
+repo_root = sys.argv[5]
+agent_os = [x for x in sys.argv[6].split(",") if x]
+areas = [x for x in sys.argv[7].split(",") if x]
+specs = [x for x in sys.argv[8].split(",") if x]
+now = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+existing = {}
+created_at = now
+if manifest.exists():
+    try:
+        old = json.loads(manifest.read_text(encoding="utf-8"))
+        created_at = old.get("created_at", created_at)
+        for item in old.get("managed_files", []):
+            if item.get("path"):
+                existing[item["path"]] = item
+    except Exception:
+        existing = {}
+
+for line in records_file.read_text(encoding="utf-8").splitlines():
+    if not line:
+        continue
+    path, source, digest, marker = (line.split("|", 3) + ["", "", "", ""])[:4]
+    existing[path] = {
+        "path": path,
+        "source": source,
+        "content_hash": digest,
+        "marker": marker,
+        "updated_at": now,
+    }
+
+skipped = [x for x in skipped_file.read_text(encoding="utf-8").splitlines() if x]
+data = {
+    "_agentic": {
+        "generated_by": "agentic",
+        "repository": repo_link,
+    },
+    "version": 1,
+    "created_at": created_at,
+    "updated_at": now,
+    "settings": {
+        "agent_os": agent_os,
+        "areas": areas,
+        "specializations": specs,
+        "source_repo": repo_link,
+        "source_checkout": repo_root,
+    },
+    "managed_files": sorted(existing.values(), key=lambda x: x["path"]),
+    "skipped_files": skipped,
+}
+manifest.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+PY
+  rm -f "$records_file" "$skipped_file"
+  unique_append "$manifest" COPIED_PATHS
+}
+
+load_install_settings_from_manifest() {
+  local manifest="$1"
+  [[ -f "$manifest" ]] || return 1
+  ensure_python_available
+
+  local values=()
+  readlines values < <(python3 - "$manifest" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+settings = data.get("settings", {})
+for key in ("agent_os", "areas", "specializations"):
+    print("::" + key)
+    for value in settings.get(key, []):
+        print(value)
+PY
+)
+
+  local section=""
+  local loaded_agent_os=()
+  local loaded_areas=()
+  local loaded_specs=()
+  local value
+  for value in "${values[@]}"; do
+    case "$value" in
+      "::agent_os") section="agent_os" ;;
+      "::areas") section="areas" ;;
+      "::specializations") section="specializations" ;;
+      *)
+        case "$section" in
+          agent_os) loaded_agent_os+=("$value") ;;
+          areas) loaded_areas+=("$value") ;;
+          specializations) loaded_specs+=("$value") ;;
+        esac
+        ;;
+    esac
+  done
+
+  if [[ "${#SELECTED_AGENT_OS[@]}" -eq 1 && "${SELECTED_AGENT_OS[0]}" == "$DEFAULT_AGENT_OS" && "${#loaded_agent_os[@]}" -gt 0 ]]; then
+    SELECTED_AGENT_OS=("${loaded_agent_os[@]}")
+  fi
+  if [[ "${#SELECTED_AREAS[@]}" -eq 0 && "${#loaded_areas[@]}" -gt 0 ]]; then
+    SELECTED_AREAS=("${loaded_areas[@]}")
+  fi
+  if [[ "${#SELECTED_SPECS[@]}" -eq 0 && "${#loaded_specs[@]}" -gt 0 ]]; then
+    SELECTED_SPECS=("${loaded_specs[@]}")
+  fi
+}
+
 path_ref_for_shell_export() {
   local dir="$1"
   if [[ "$dir" == "$HOME/"* ]]; then
@@ -583,11 +974,483 @@ copy_dir_contents() {
   local dest="$2"
   ensure_dir "$dest"
   if [[ "$DRY_RUN" == true ]]; then
-    log "DRY-RUN cp -a $src/. $dest/"
+    log "DRY-RUN copy managed contents $src -> $dest"
+    unique_append "$dest" COPIED_PATHS
+    return
+  fi
+
+  local event kind value events_file
+  events_file="$(mktemp "${TMPDIR:-/tmp}/agentic-copy-events.XXXXXX")"
+  python3 - "$src" "$dest" "$REPO_ROOT" "$PROJECT_DIR" "$(project_manifest_path)" "$APP_REPO_LINK" > "$events_file" <<'PY'
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+src = Path(sys.argv[1])
+dest_root = Path(sys.argv[2])
+repo_root = Path(sys.argv[3])
+project_dir = Path(sys.argv[4])
+manifest = Path(sys.argv[5])
+repo = sys.argv[6]
+
+
+def emit(kind: str, value: str) -> None:
+    print(f"{kind}\t{value}")
+
+
+def sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+managed = None
+if manifest.exists():
+    managed = {}
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+        for item in data.get("managed_files", []):
+            rel = item.get("path")
+            if rel:
+                managed[rel] = item.get("content_hash", "")
+    except Exception:
+        managed = {}
+
+
+def rel_to_project(path: Path) -> str:
+    try:
+        return str(path.relative_to(project_dir))
+    except ValueError:
+        return str(path)
+
+
+def rel_to_repo(path: Path) -> str:
+    try:
+        return str(path.relative_to(repo_root))
+    except ValueError:
+        return str(path)
+
+
+def yaml_quote(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def markdown_with_marker(body: str, source_ref: str) -> str:
+    block = (
+        "agentic:\n"
+        "  generated_by: agentic\n"
+        f"  source: {yaml_quote(source_ref)}\n"
+        f"  repository: {yaml_quote(repo)}\n"
+    )
+    if body.startswith("---\n"):
+        end = body.find("\n---", 4)
+        if end != -1:
+            return body[: end + 1] + block + body[end + 1 :]
+    return "---\n" + block + "---\n" + body
+
+
+def commented(body: str, prefix: str, source_ref: str) -> str:
+    marker = f"Generated by agentic; source: {source_ref}; repository: {repo}"
+    line = f"{prefix} {marker}\n"
+    if body.startswith("#!"):
+        first, sep, rest = body.partition("\n")
+        if sep:
+            return first + sep + line + rest
+    return line + body
+
+
+def add_marker(file_path: Path, target: Path, source_ref: str) -> str:
+    text = file_path.read_text(encoding="utf-8")
+    suffix = target.suffix.lower()
+    if suffix == ".md":
+        return markdown_with_marker(text, source_ref)
+    if suffix == ".json":
+        data = json.loads(text)
+        if not isinstance(data, dict):
+            raise SystemExit(f"Cannot add agentic metadata to non-object JSON: {target}")
+        data["_agentic"] = {
+            "generated_by": "agentic",
+            "source": source_ref,
+            "repository": repo,
+        }
+        return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+    if suffix in {".ts", ".tsx", ".js", ".jsx", ".css"}:
+        return commented(text, "//", source_ref)
+    if suffix in {".sh", ".toml", ".py", ".yml", ".yaml"}:
+        return commented(text, "#", source_ref)
+    return commented(text, "#", source_ref)
+
+
+emit("DIR", str(dest_root))
+for file_path in sorted(p for p in src.rglob("*") if p.is_file()):
+    rel = file_path.relative_to(src)
+    target = dest_root / rel
+    project_rel = rel_to_project(target)
+    source_ref = rel_to_repo(file_path)
+
+    if managed is not None:
+        if project_rel not in managed:
+            if target.exists():
+                emit("WARN", f"Skipping unmanaged target on rerun: {project_rel}")
+                emit("SKIP", project_rel)
+                continue
+        expected_hash = managed.get(project_rel, "")
+        if target.exists() and expected_hash and sha256(target) != expected_hash:
+            emit("WARN", f"Skipping user-modified managed file: {project_rel}")
+            emit("SKIP", project_rel)
+            continue
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    emit("DIR", str(target.parent))
+    target.write_text(add_marker(file_path, target, source_ref), encoding="utf-8")
+    digest = sha256(target)
+    emit("RECORD", f"{project_rel}|{source_ref}|{digest}|internal")
+    emit("COPIED", str(target))
+PY
+  while IFS= read -r event || [[ -n "$event" ]]; do
+    kind="${event%%	*}"
+    if [[ "$kind" == "$event" ]]; then
+      value=""
+    else
+      value="${event#*	}"
+    fi
+    record_agentic_event "$kind" "$value"
+  done < "$events_file"
+  rm -f "$events_file"
+}
+
+write_generated_text_file() {
+  local dest="$1"
+  local source_ref="$2"
+  local content="$3"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN write generated file $dest"
+    unique_append "$dest" COPIED_PATHS
+    return
+  fi
+
+  can_write_managed_file "$dest" || return 0
+  ensure_dir "$(dirname -- "$dest")"
+
+  local tmp
+  tmp="$(mktemp "${TMPDIR:-/tmp}/agentic-generated.XXXXXX")"
+  printf '%s' "$content" > "$tmp"
+  write_file_with_agentic_marker "$tmp" "$dest" "$source_ref"
+  rm -f "$tmp"
+}
+
+write_json_file_with_agentic_metadata() {
+  local dest="$1"
+  local source_ref="$2"
+  local python_body="$3"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN update JSON managed file $dest"
+    unique_append "$dest" COPIED_PATHS
+    return
+  fi
+
+  can_write_managed_file "$dest" || return 0
+  ensure_dir "$(dirname -- "$dest")"
+  python3 - "$dest" "$source_ref" "$APP_REPO_LINK" "$CONTEXT7_API_KEY" "$python_body" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+source_ref = sys.argv[2]
+repo = sys.argv[3]
+context7_api_key = sys.argv[4]
+body = sys.argv[5]
+
+data = {}
+if path.exists():
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        data = {}
+if not isinstance(data, dict):
+    data = {}
+
+namespace = {
+    "data": data,
+    "context7_api_key": context7_api_key,
+}
+exec(body, namespace)
+data = namespace["data"]
+data["_agentic"] = {
+    "generated_by": "agentic",
+    "source": source_ref,
+    "repository": repo,
+}
+path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+PY
+  register_managed_file "$dest" "$source_ref" "internal"
+}
+
+write_json_config_file() {
+  local dest="$1"
+  local source_ref="$2"
+  local python_body="$3"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN update JSON config file $dest"
+    unique_append "$dest" COPIED_PATHS
+    return
+  fi
+
+  can_write_managed_file "$dest" || return 0
+  ensure_dir "$(dirname -- "$dest")"
+  python3 - "$dest" "$CONTEXT7_API_KEY" "$python_body" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+context7_api_key = sys.argv[2]
+body = sys.argv[3]
+
+data = {}
+if path.exists():
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        data = {}
+if not isinstance(data, dict):
+    data = {}
+
+namespace = {
+    "data": data,
+    "context7_api_key": context7_api_key,
+}
+exec(body, namespace)
+data = namespace["data"]
+path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+PY
+  register_managed_file "$dest" "$source_ref" "config"
+}
+
+write_context7_opencode_config() {
+  local dest="$PROJECT_DIR/opencode.json"
+  local body
+  body='
+mcp = data.setdefault("mcp", {})
+context7 = {
+    "type": "remote",
+    "url": "https://mcp.context7.com/mcp",
+    "enabled": True,
+}
+if context7_api_key:
+    context7["headers"] = {"CONTEXT7_API_KEY": context7_api_key}
+mcp["context7"] = context7
+'
+  write_json_config_file "$dest" "generated:context7-opencode-config" "$body"
+}
+
+write_context7_opencode_legacy_config() {
+  local dest="$PROJECT_DIR/.opencode/opencode.json"
+  local body
+  body='
+mcp = data.setdefault("mcp", {})
+context7 = {
+    "type": "remote",
+    "url": "https://mcp.context7.com/mcp",
+    "enabled": True,
+}
+if context7_api_key:
+    context7["headers"] = {"CONTEXT7_API_KEY": context7_api_key}
+mcp["context7"] = context7
+'
+  write_json_file_with_agentic_metadata "$dest" "generated:context7-opencode-legacy-config" "$body"
+}
+
+write_context7_codex_config() {
+  local dest="$PROJECT_DIR/.codex/config.toml"
+  local headers=""
+  if [[ -n "$CONTEXT7_API_KEY" ]]; then
+    local escaped_key
+    escaped_key="${CONTEXT7_API_KEY//\\/\\\\}"
+    escaped_key="${escaped_key//\"/\\\"}"
+    headers="http_headers = { \"CONTEXT7_API_KEY\" = \"$escaped_key\" }
+"
+  fi
+  write_generated_text_file "$dest" "generated:context7-codex-config" "[mcp_servers.context7]
+url = \"https://mcp.context7.com/mcp\"
+${headers}"
+}
+
+write_context7_claude_config() {
+  local dest="$PROJECT_DIR/.mcp.json"
+  local body
+  body='
+mcp_servers = data.setdefault("mcpServers", {})
+context7 = {
+    "type": "http",
+    "url": "https://mcp.context7.com/mcp",
+}
+if context7_api_key:
+    context7["headers"] = {"CONTEXT7_API_KEY": context7_api_key}
+mcp_servers["context7"] = context7
+'
+  write_json_config_file "$dest" "generated:context7-claude-config" "$body"
+}
+
+write_context7_cursor_config() {
+  local dest="$PROJECT_DIR/.cursor/mcp.json"
+  local body
+  body='
+mcp_servers = data.setdefault("mcpServers", {})
+context7 = {
+    "url": "https://mcp.context7.com/mcp",
+}
+if context7_api_key:
+    context7["headers"] = {"CONTEXT7_API_KEY": context7_api_key}
+mcp_servers["context7"] = context7
+'
+  write_json_config_file "$dest" "generated:context7-cursor-config" "$body"
+}
+
+write_context7_gemini_config() {
+  local dest="$PROJECT_DIR/.gemini/settings.json"
+  local body
+  body='
+mcp_servers = data.setdefault("mcpServers", {})
+context7 = {
+    "httpUrl": "https://mcp.context7.com/mcp",
+}
+if context7_api_key:
+    context7["headers"] = {"CONTEXT7_API_KEY": context7_api_key}
+mcp_servers["context7"] = context7
+'
+  write_json_config_file "$dest" "generated:context7-gemini-config" "$body"
+}
+
+configure_context7_if_needed() {
+  if ! selected_agent_os_contains "opencode" \
+    && ! selected_agent_os_contains "codex" \
+    && ! selected_agent_os_contains "claude" \
+    && ! selected_agent_os_contains "cursor" \
+    && ! selected_agent_os_contains "gemini"; then
+    return
+  fi
+
+  if is_interactive_terminal; then
+    local enable_context7 answer
+    read -r -p "Enable Context7 MCP configuration? [y/N]: " enable_context7
+    enable_context7="$(trim "$enable_context7")"
+    if [[ ! "$enable_context7" =~ ^[Yy]$ ]]; then
+      log "Context7 MCP configuration disabled"
+      return
+    fi
+
+    if [[ -z "$CONTEXT7_API_KEY" ]]; then
+      read -r -p "Context7 API key (optional, empty = no key): " answer
+      CONTEXT7_API_KEY="$(trim "$answer")"
+    fi
+  elif [[ -z "$CONTEXT7_API_KEY" ]]; then
+    log "Context7 MCP configuration skipped; set CONTEXT7_API_KEY or use an interactive install to enable it"
+    return
+  fi
+
+  if selected_agent_os_contains "opencode"; then
+    write_context7_opencode_config
+    write_context7_opencode_legacy_config
+  fi
+
+  if selected_agent_os_contains "codex"; then
+    write_context7_codex_config
+  fi
+
+  if selected_agent_os_contains "claude"; then
+    write_context7_claude_config
+  fi
+
+  if selected_agent_os_contains "cursor"; then
+    write_context7_cursor_config
+  fi
+
+  if selected_agent_os_contains "gemini"; then
+    write_context7_gemini_config
+  fi
+}
+
+write_default_opencode_plugin_config() {
+  ensure_dir "$APP_CONFIG_DIR"
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN write disabled opencode plugin config to $OPENCODE_PLUGIN_CONFIG_FILE"
   else
-    cp -a "$src/." "$dest/"
+    python3 - "$OPENCODE_PLUGIN_CONFIG_FILE" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+path.write_text(json.dumps({
+    "telegram": {"enabled": False, "botToken": "", "chatId": ""},
+    "modelChecker": {"enabled": False},
+}, indent=2) + "\n", encoding="utf-8")
+PY
   fi
-  unique_append "$dest" COPIED_PATHS
+}
+
+configure_opencode_plugins_if_needed() {
+  selected_agent_os_contains "opencode" || return 0
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN configure optional opencode plugins"
+    return
+  fi
+
+  ensure_python_available
+  ensure_dir "$APP_CONFIG_DIR"
+
+  if ! is_interactive_terminal; then
+    if [[ ! -f "$OPENCODE_PLUGIN_CONFIG_FILE" ]]; then
+      write_default_opencode_plugin_config
+    fi
+    return
+  fi
+
+  local enable_telegram telegram_token telegram_chat enable_model_checker
+  read -r -p "Enable OpenCode Telegram notifications? [y/N]: " enable_telegram
+  enable_telegram="$(trim "$enable_telegram")"
+  telegram_token=""
+  telegram_chat=""
+  if [[ "$enable_telegram" =~ ^[Yy]$ ]]; then
+    read -r -p "Telegram bot token (empty disables plugin): " telegram_token
+    read -r -p "Telegram chat id (empty disables plugin): " telegram_chat
+    telegram_token="$(trim "$telegram_token")"
+    telegram_chat="$(trim "$telegram_chat")"
+  fi
+
+  read -r -p "Enable OpenCode model checker plugin? [y/N]: " enable_model_checker
+  enable_model_checker="$(trim "$enable_model_checker")"
+
+  python3 - "$OPENCODE_PLUGIN_CONFIG_FILE" "$telegram_token" "$telegram_chat" "$enable_model_checker" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+token = sys.argv[2]
+chat = sys.argv[3]
+enable_model = sys.argv[4].lower() == "y"
+data = {
+    "telegram": {
+        "enabled": bool(token and chat),
+        "botToken": token,
+        "chatId": chat,
+    },
+    "modelChecker": {
+        "enabled": enable_model,
+    },
+}
+path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+PY
 }
 
 normalize_selected_agent_os() {
@@ -756,15 +1619,18 @@ generate_agents_md() {
   fi
 
   ensure_dir "$project_dir"
-  build_header "$out"
-  append_root_agents_template "$out"
+  local tmp
+  tmp="$(mktemp "${TMPDIR:-/tmp}/agentic-agents.XXXXXX")"
+  build_header "$tmp"
+  append_root_agents_template "$tmp"
 
   local spec_key
   for spec_key in "${SELECTED_SPECS[@]}"; do
-    append_specialization_template "$out" "$spec_key"
+    append_specialization_template "$tmp" "$spec_key"
   done
 
-  unique_append "$out" COPIED_PATHS
+  write_file_with_agentic_marker "$tmp" "$out" "generated:AGENTS.md"
+  rm -f "$tmp"
 }
 
 validate_inputs() {
@@ -870,13 +1736,17 @@ print_report() {
 
 run_install() {
   ensure_repo_layout
+  ensure_python_available
   normalize_selected_agent_os
   validate_inputs
 
   ensure_dir "$PROJECT_DIR"
+  configure_opencode_plugins_if_needed
   copy_extensions "$PROJECT_DIR"
   copy_specialization_assets "$PROJECT_DIR"
   generate_agents_md "$PROJECT_DIR"
+  configure_context7_if_needed
+  write_agentic_manifest "$PROJECT_DIR"
   print_report
 }
 
@@ -1256,7 +2126,9 @@ run_tui() {
   if [[ "$use_fzf" == true ]]; then
     readlines picked_agent_os < <(choose_multi_fzf "Select Agent OS target(s):" "${agentos_choices[@]}")
   else
-    readlines picked_agent_os < <(choose_multi_by_index "Select Agent OS target(s):" "${agentos_choices[@]}")
+    local picked_agent_os_output
+    picked_agent_os_output="$(choose_multi_by_index "Select Agent OS target(s):" "${agentos_choices[@]}")"
+    readlines picked_agent_os <<< "$picked_agent_os_output"
   fi
   if [[ "${#picked_agent_os[@]}" -eq 0 ]]; then
     SELECTED_AGENT_OS=("$DEFAULT_AGENT_OS")
@@ -1271,7 +2143,9 @@ run_tui() {
   if [[ "$use_fzf" == true ]]; then
     readlines picked_areas < <(choose_multi_fzf "Select area(s):" "${areas[@]}")
   else
-    readlines picked_areas < <(choose_multi_by_index "Select area(s):" "${areas[@]}")
+    local picked_areas_output
+    picked_areas_output="$(choose_multi_by_index "Select area(s):" "${areas[@]}")"
+    readlines picked_areas <<< "$picked_areas_output"
   fi
 
   if [[ "${#picked_areas[@]}" -eq 0 ]]; then
@@ -1290,7 +2164,9 @@ run_tui() {
     if [[ "$use_fzf" == true ]]; then
       readlines chosen_specs < <(choose_multi_fzf "Select specialization(s) for '$area':" "${specs[@]}")
     else
-      readlines chosen_specs < <(choose_multi_by_index "Select specialization(s) for '$area':" "${specs[@]}")
+      local chosen_specs_output
+      chosen_specs_output="$(choose_multi_by_index "Select specialization(s) for '$area':" "${specs[@]}")"
+      readlines chosen_specs <<< "$chosen_specs_output"
     fi
 
     if [[ "${#chosen_specs[@]}" -eq 0 ]]; then
@@ -1325,6 +2201,22 @@ self_install() {
 
   ensure_dir "$bin_dir"
 
+  if [[ -e "$source_path" && -e "$target" ]]; then
+    local source_real target_real
+    source_real="$(cd -- "$(dirname -- "$source_path")" && pwd -P)/$(basename -- "$source_path")"
+    target_real="$(cd -- "$(dirname -- "$target")" && pwd -P)/$(basename -- "$target")"
+    if [[ "$source_real" == "$target_real" ]]; then
+      if [[ -e "$APP_REPO_DIR/agentic" ]]; then
+        source_path="$APP_REPO_DIR/agentic"
+      else
+        log "Source and target are already the same file: $target"
+        log "Nothing to copy. Run '$APP_NAME upgrade' first to refresh the knowledge base checkout, or run self-install from a checkout."
+        self_install_fzf_optional
+        return
+      fi
+    fi
+  fi
+
   if [[ -e "$target" ]] && [[ "$SELF_INSTALL_FORCE" != true ]]; then
     error "Target already exists: $target"
     error "Use --force to overwrite"
@@ -1363,6 +2255,30 @@ self_install() {
   echo "Dry-run: $DRY_RUN"
 }
 
+update_installed_binary_from_repo() {
+  local source_path="$APP_REPO_DIR/agentic"
+  local target="$SCRIPT_SOURCE"
+
+  if [[ ! -r "$source_path" ]]; then
+    warn "Cannot self-update installed binary; source not found: $source_path"
+    return
+  fi
+
+  if [[ "$DRY_RUN" == true ]]; then
+    log "DRY-RUN self-update installed binary $target from $source_path"
+    return
+  fi
+
+  if cmp -s "$source_path" "$target"; then
+    log "Installed binary already up to date: $target"
+    return
+  fi
+
+  cp "$source_path" "$target"
+  chmod +x "$target"
+  log "Updated installed binary: $target"
+}
+
 upgrade_repo_checkout() {
   refresh_repo_paths
 
@@ -1392,6 +2308,21 @@ upgrade_repo_checkout() {
   git -C "$APP_REPO_DIR" pull --ff-only
   refresh_repo_paths
   ensure_repo_layout
+  update_installed_binary_from_repo
+}
+
+sync_current_project_after_upgrade() {
+  local manifest="$PWD/$PROJECT_MANIFEST_NAME"
+  if [[ ! -f "$manifest" ]]; then
+    log "No $PROJECT_MANIFEST_NAME in current directory; knowledge base upgrade complete"
+    return
+  fi
+
+  log "Detected managed project in $PWD; syncing from upgraded knowledge base"
+  PROJECT_DIR="$(pwd -P)"
+  load_install_settings_from_manifest "$manifest"
+  ensure_repo_layout
+  run_install
 }
 
 parse_theme_option() {
@@ -1499,6 +2430,12 @@ case "$COMMAND" in
           ;;
       esac
     done
+    if [[ -z "$PROJECT_DIR" && -f "$PWD/$PROJECT_MANIFEST_NAME" ]]; then
+      PROJECT_DIR="$PWD"
+      load_install_settings_from_manifest "$PWD/$PROJECT_MANIFEST_NAME"
+    elif [[ -n "$PROJECT_DIR" && -f "$PROJECT_DIR/$PROJECT_MANIFEST_NAME" ]]; then
+      load_install_settings_from_manifest "$PROJECT_DIR/$PROJECT_MANIFEST_NAME"
+    fi
     ensure_repo_available_for_command
     ensure_repo_layout
     set_theme_colors
@@ -1557,6 +2494,7 @@ case "$COMMAND" in
       esac
     done
     upgrade_repo_checkout
+    sync_current_project_after_upgrade
     ;;
 
   self-install)