auto-context-cli 1.0.0__py3-none-any.whl

auto_context/config.py

@@ -0,0 +1,65 @@
+"""
+config.py — Global path constants and runtime configuration.
+
+All path logic is centralised here so every other module can import
+a single named constant rather than re-computing home directories.
+"""
+import importlib.resources as _pkg_resources
+from pathlib import Path
+
+
+def get_templates_dir() -> Path:
+    """
+    Return the templates directory in a way that works both during development
+    (uv run / editable install) and after a wheel install (uv tool install .).
+
+    importlib.resources.files() is the PEP 451-compliant way to locate data
+    files that are bundled inside a Python package, regardless of whether the
+    package is installed as a wheel, a zip, or an editable source tree.
+    """
+    try:
+        # Python 3.9+ path — works in wheel and editable installs
+        ref = _pkg_resources.files("auto_context").joinpath("templates")
+        # Materialise to a real Path so callers can use glob(), iterdir(), etc.
+        with _pkg_resources.as_file(ref) as p:
+            return p
+    except Exception:
+        # Hard fallback: source-tree layout (should never be reached in practice)
+        return Path(__file__).parent / "templates"
+
+
+# ── User home-relative roots ───────────────────────────────────────────────────
+HOME = Path.home()
+
+# Central memory brain (~/.auto-context/memory)
+MEMORY_DIR: Path = HOME / ".auto-context" / "memory"
+
+# Global plugin scope consumed by Antigravity / Gemini CLI
+GLOBAL_PLUGIN_DIR: Path = HOME / ".gemini" / "config" / "plugins" / "auto-context"
+GLOBAL_GEMINI_DIR: Path = HOME / ".gemini" / "config"
+
+# Subdirectory conventions (relative to any project or plugin root)
+RULES_SUBDIR = "rules"
+SKILLS_SUBDIR = "skills"
+AGENTS_SUBDIR = ".agents"
+GEMINI_SUBDIR = ".gemini"
+
+# ── Stack detection: indicator files → (stack_label, framework_hint_key) ──────
+STACK_INDICATORS: list[tuple[str, str, str]] = [
+    # (filename, stack_label, framework_key_for_content_scan)
+    ("package.json", "Node.js / JavaScript / TypeScript", "js"),
+    ("pyproject.toml", "Python", "py"),
+    ("requirements.txt", "Python", "py"),
+    ("Pipfile", "Python", "py"),
+    ("go.mod", "Go (Golang)", "go"),
+    ("Cargo.toml", "Rust", "rust"),
+    ("pom.xml", "Java / Kotlin", "jvm"),
+    ("build.gradle", "Java / Kotlin", "jvm"),
+    ("docker-compose.yml", "Dockerized Container", "docker"),
+    ("Dockerfile", "Dockerized Container", "docker"),
+]
+
+# ── Git commit message templates ───────────────────────────────────────────────
+GIT_COMMIT_INIT = "feat(memory): initialize central agent brain knowledge base"
+GIT_COMMIT_SYNC = "chore(memory): sync agent brain knowledge base"
+

auto_context/main.py

@@ -0,0 +1,121 @@
+"""
+main.py — Root Typer app and CLI entrypoint.
+
+Supports both modern subcommands (rule, skill, mcp, memory, share, import)
+and legacy flag compatibility (-r, -s, --add-mcp, --list-mcp, --remove-mcp).
+"""
+from importlib.metadata import version as pkg_version
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from auto_context.commands import init_cmd, memory, mcp, share, import_cmd
+
+app = typer.Typer(
+    name="init-context",
+    help="Autonomous context & instruction manager for AI coding assistants.",
+    no_args_is_help=False,
+    add_completion=False,
+)
+console = Console()
+
+# ── Sub-routers ────────────────────────────────────────────────────────────────
+app.add_typer(memory.app, name="memory", help="Central memory brain management.")
+app.add_typer(mcp.app, name="mcp", help="MCP tool registry management.")
+
+# ── Inline subcommands ────────────────────────────────────────────────────────
+app.command("init")(init_cmd.init)
+app.command("rule")(init_cmd.new_rule)
+app.command("skill")(init_cmd.new_skill)
+app.command("share")(share.share)
+app.command("import")(import_cmd.import_item)
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    target: Annotated[Optional[Path], typer.Option("--target", "-t", help="Target project directory.")] = None,
+    new_rule: Annotated[Optional[str], typer.Option("--new-rule", "-r", help="Scaffold a new agent rule.")] = None,
+    new_skill: Annotated[Optional[str], typer.Option("--new-skill", "-s", help="Scaffold a new agent skill.")] = None,
+    add_mcp: Annotated[Optional[str], typer.Option("--add-mcp", help="Add or update an MCP server.")] = None,
+    remove_mcp: Annotated[Optional[str], typer.Option("--remove-mcp", help="Remove an MCP server.")] = None,
+    list_mcp: Annotated[bool, typer.Option("--list-mcp", help="List registered MCP servers.")] = False,
+    preset: Annotated[Optional[str], typer.Option("--preset", "-p", help="MCP preset name.")] = None,
+    runtime: Annotated[Optional[str], typer.Option("--runtime", "--runner", help="Package runner (uvx vs npx).")] = None,
+    command: Annotated[Optional[str], typer.Option("--command", "-c", help="Executable command for MCP server.")] = None,
+    args: Annotated[Optional[str], typer.Option("--args", "-a", help="Arguments to pass to MCP command.")] = None,
+    url: Annotated[Optional[str], typer.Option("--url", help="HTTP endpoint URL for remote MCP server.")] = None,
+    env_var: Annotated[Optional[str], typer.Option("--env-var", help="Secret environment variable name.")] = None,
+    env: Annotated[Optional[str], typer.Option("--env", help="Environment variables (KEY=val,KEY2=val2).")] = None,
+    global_: Annotated[bool, typer.Option("--global", "-g", help="Target global plugin scope.")] = False,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite existing files.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", "-d", help="Preview without writing.")] = False,
+    version: bool = typer.Option(False, "--version", "-v", help="Show version and exit."),
+) -> None:
+    """
+    Run without a subcommand to scaffold project context, or use flags for
+    rules (-r), skills (-s), MCP (--add-mcp), and options.
+    """
+    if version:
+        try:
+            v = pkg_version("auto-context-cli")
+        except Exception:
+            try:
+                v = pkg_version("auto-context")
+            except Exception:
+                v = "1.0.0"
+        console.print(f"init-context v{v}")
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # ── Legacy flag routing ────────────────────────────────────────────────────
+    if new_rule:
+        init_cmd.new_rule(name=new_rule, target=target, global_=global_, force=force, dry_run=dry_run)
+        return
+
+    if new_skill:
+        init_cmd.new_skill(name=new_skill, target=target, global_=global_, force=force, dry_run=dry_run)
+        return
+
+    if list_mcp:
+        mcp.list_mcp(target=target, global_=global_)
+        return
+
+    if remove_mcp:
+        mcp.remove_mcp(name=remove_mcp, target=target, global_=global_)
+        return
+
+    if add_mcp:
+        mcp.add_mcp(
+            name=add_mcp,
+            target=target,
+            global_=global_,
+            preset=preset,
+            runtime=runtime,
+            command=command,
+            args=args,
+            url=url,
+            env_var=env_var,
+            env=env,
+        )
+        return
+
+    # Default action: scaffold workspace
+    init_cmd.init(target=target, force=force, dry_run=dry_run)
+
+
+def main() -> None:  # pragma: no cover
+    import os, sys
+    # Ensure UTF-8 output on all platforms (Windows CP1252 fix)
+    if sys.platform == "win32":
+        os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        except AttributeError:
+            pass
+    app()

auto_context/security.py

@@ -0,0 +1,162 @@
+"""
+security.py — Zero-bypass secret scanner and key auditor.
+
+Pure-Python port of the PowerShell Test-SecretSafety function.
+Uses rich for coloured terminal output instead of raw ANSI codes.
+
+Public API:
+    audit_path(path, single_file=False) -> list[Violation]
+    print_report(violations)            -> None  (prints via rich)
+    abort_if_violations(violations)     -> None  (sys.exit(1) on findings)
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+from rich.text import Text
+
+console = Console(stderr=True)
+
+# ── Prohibited filenames & extensions ────────────────────────────────────────
+PROHIBITED_FILES: frozenset[str] = frozenset({
+    ".env", ".env.local", ".env.production", ".env.development",
+    ".env.test", ".env.staging", "id_rsa", "id_rsa.pub",
+    "id_ed25519", "id_ed25519.pub", "id_ecdsa", "id_ecdsa.pub",
+    "id_dsa", "id_dsa.pub", "authorized_keys", "known_hosts",
+})
+
+PROHIBITED_EXTENSIONS: frozenset[str] = frozenset({
+    ".pem", ".key", ".pkcs12", ".p12", ".pfx", ".kdbx",
+})
+
+# ── Secret patterns (name → compiled regex) ──────────────────────────────────
+_RAW_PATTERNS: list[tuple[str, str]] = [
+    ("GitHub Token",               r"(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{36,}"),
+    ("GitHub Fine-grained PAT",    r"github_pat_[A-Za-z0-9_]{50,}"),
+    ("Stripe Live Key",            r"sk_live_[0-9a-zA-Z]{24,}"),
+    ("OpenAI API Key",             r"sk-[a-zA-Z0-9_\-]{32,}"),
+    ("Anthropic API Key",          r"sk-ant-[a-zA-Z0-9_\-]{32,}"),
+    ("OpenAI Project Key",         r"sk-proj-[a-zA-Z0-9_\-]{40,}"),
+    ("Google API Key",             r"AIza[0-9A-Za-z\-_]{35}"),
+    ("AWS Access Key ID",          r"AKIA[0-9A-Z]{16}"),
+    ("Private Key Block",          r"-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"),
+    ("Hardcoded Secret/Password",
+     r'(?i)(?:password|secret|api[_-]?key|access[_-]?token)\s*[:=]\s*[\'"]'
+     r'(?!(?:YOUR_|REPLACE_|MOCK_|TEST_|DUMMY_|\{\{|<))'
+     r'[A-Za-z0-9_\-\.\$\!\@\#\%\^\&\*\(\)\+]{8,}[\'"]'),
+]
+
+PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    (name, re.compile(pattern)) for name, pattern in _RAW_PATTERNS
+]
+
+
+@dataclass(slots=True)
+class Violation:
+    """A single security finding."""
+    file: Path
+    line: int          # 0 = filename-level violation
+    pattern: str
+    preview: str       # masked token preview
+
+
+# ── Core scanner ─────────────────────────────────────────────────────────────
+
+def _mask(token: str) -> str:
+    """Return a partially-masked token for safe display."""
+    if len(token) <= 8:
+        return "****"
+    return token[:4] + "*" * (len(token) - 8) + token[-4:]
+
+
+def _scan_file(path: Path) -> list[Violation]:
+    """Return violations found in a single file."""
+    violations: list[Violation] = []
+    name = path.name
+    suffix = path.suffix.lower()
+
+    # Filename-level checks
+    if name in PROHIBITED_FILES or name.startswith(".env."):
+        return [Violation(path, 0, "Prohibited Sensitive File", name)]
+    if suffix in PROHIBITED_EXTENSIONS:
+        return [Violation(path, 0, "Prohibited Key/Certificate Extension", name)]
+
+    # Content scan (skip binary-looking files gracefully)
+    try:
+        lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+    except OSError:
+        return violations
+
+    for lineno, line in enumerate(lines, start=1):
+        for pattern_name, regex in PATTERNS:
+            m = regex.search(line)
+            if m:
+                violations.append(Violation(path, lineno, pattern_name, _mask(m.group())))
+                break  # one finding per line is enough
+
+    return violations
+
+
+def audit_path(path: Path, *, single_file: bool = False) -> list[Violation]:
+    """
+    Scan *path* for secrets and prohibited files.
+
+    Args:
+        path:        File or directory to scan.
+        single_file: When True, treat *path* as a single file even if it is
+                     a directory (mirrors the original -Mode "File" flag).
+
+    Returns:
+        List of Violation objects (empty = clean).
+    """
+    violations: list[Violation] = []
+
+    if single_file or path.is_file():
+        if path.exists():
+            violations.extend(_scan_file(path))
+    else:
+        for child in path.rglob("*"):
+            # Skip .git internals
+            if ".git" in child.parts:
+                continue
+            if child.is_file():
+                violations.extend(_scan_file(child))
+
+    return violations
+
+
+# ── Rich reporter ─────────────────────────────────────────────────────────────
+
+def print_report(violations: list[Violation]) -> None:
+    """Print a rich-formatted security report to stderr."""
+    if not violations:
+        console.print("[bold green][✓] Security Audit Passed:[/] 0 sensitive credentials detected.")
+        return
+
+    console.print(
+        f"\n[bold red][✗] SECURITY AUDIT VIOLATION — {len(violations)} finding(s):[/]"
+    )
+    for v in violations:
+        loc = f"Line {v.line}" if v.line > 0 else "Filename"
+        line = Text()
+        line.append("   • ", style="yellow")
+        line.append(str(v.file), style="cyan")
+        line.append(f" [{loc}]: ", style="white")
+        line.append(v.pattern, style="bold red")
+        line.append(f" (preview: {v.preview})", style="dim")
+        console.print(line)
+
+
+def abort_if_violations(violations: list[Violation]) -> None:
+    """Print the report and exit with code 1 if any violations exist."""
+    print_report(violations)
+    if violations:
+        console.print(
+            "\n[bold red][✗] ABORT:[/] Remove credentials before committing or sharing.\n"
+        )
+        sys.exit(1)
+

auto_context/templates/AGENTS.template.md

@@ -0,0 +1,49 @@
+# Standing Agent Rules for {{PROJECT_NAME}}
+
+## Critical Mandate: Autonomous `context.md` Synchronization & Self-Evolution
+As an AI coding assistant working in this repository (`{{PROJECT_DIR}}`), you are **strictly mandated** to keep `{{PROJECT_DIR}}/context.md` continuously up to date and autonomously learn, persist, and crystallize new rules and skills. The user must **never** need to remind or instruct you.
+
+### 1. Mandatory Post-Action Protocol
+Whenever ANY of the following events occur in any session or conversation turn:
+- A configuration file or script is created, edited, moved, or deleted.
+- A problem, bug, or error is encountered and diagnosed.
+- Credentials, tokens, user accounts, or security keys are generated or updated.
+- Architectural decisions or operational steps are modified.
+
+**You MUST immediately update `{{PROJECT_DIR}}/context.md` before finalizing your response.**
+
+### 2. Autonomous Learning & Self-Evolution Protocol
+Whenever you learn a new pattern, receive a correction, observe a coding preference, or resolve a complex repeatable problem:
+1. **Identify the Type:**
+   - **Rule:** If it is a constraint, coding standard, safety boundary, or architectural preference -> Create a Rule (`init-context -r <name>`).
+   - **Skill:** If it is a multi-step procedure, deployment workflow, diagnosis runbook, or CLI sequence -> Create a Skill (`init-context -s <name>`).
+2. **Scope Decision:**
+   - **Project-Specific:** Save in `.agents/rules/` or `.agents/skills/`.
+   - **Machine-Wide / Global:** If it applies to all projects, use `--global` (`-g`) to register in `~/.gemini/config/plugins/auto-context/`.
+3. **Execution:**
+   - Use the `init-context` CLI tool to scaffold the file.
+   - Populate it with clear objectives, constraints, or step-by-step instructions.
+   - Inform the user of the new rule or skill codified.
+
+### 3. Tool Access: `init-context`
+You have native access to run `init-context` via terminal commands:
+- `init-context`: Scaffolds or repairs project context.
+- `init-context -r <rule-name> [-g]`: Creates a new rule with frontmatter.
+- `init-context -s <skill-name> [-g]`: Creates a new skill with frontmatter.
+
+### 4. Required Content & Structure in `context.md`
+1. **Master Credentials & Configuration Vault (Section 1):** Keep all ports, IPs, secrets, tokens, and endpoints synchronized.
+2. **Chronological Problem Log & Technical Solutions (Section 2):** Document symptom, root cause, exact commands/code used, and update Mermaid diagram.
+3. **Architecture & Component Layout (Section 3):** Keep stack overview and directory maps accurate.
+4. **Operations Runbook (Section 4):** Ensure 1-step reproduction instructions remain functional.
+
+### 5. Local Sandbox Credentials & Dummy Test Fixtures (`context.local.md`)
+- **Inspection Mandate:** When testing local dev servers, performing browser automation (Playwright/Puppeteer), or authenticating API endpoints, ALWAYS read `context.local.md` first before prompting the user for credentials.
+- **Strict Mock Boundary:** ONLY store dummy test credentials, mock accounts (`admin@test.local`), seed users, and local dev ports in `context.local.md`.
+- **Zero Real Secrets:** Real production secrets, payment keys, or personal tokens MUST NEVER be stored in `context.local.md` or `context.md`; reference them via `.env` or system environment variables.
+- **Git Protection:** Ensure `context.local.md` remains strictly ignored by Git (`.gitignore`) and protected with `chmod 600`.
+
+### 6. Two-Tier Progressive Disclosure Protocol (Token Optimization)
+- **Initial Boot Budget:** NEVER read full `SKILL.md` files into the initial context. Use Section 5 of `context.md` for lightweight routing (< 800 tokens).
+- **Dynamic On-Demand Loading:** Only when a user prompt matches a skill's triggers (e.g. "docker", "rebase", "diagnostics", "browser"), dynamically inspect the file using `read_file`.
+- **Zero Session Bloat:** Once the task concludes, do not keep the full skill body in persistent memory.

auto_context/templates/GEMINI.template.md

@@ -0,0 +1,49 @@
+# Standing Agent Rules for {{PROJECT_NAME}}
+
+## Critical Mandate: Autonomous `context.md` Synchronization & Self-Evolution
+As an AI coding assistant working in this repository (`{{PROJECT_DIR}}`), you are **strictly mandated** to keep `{{PROJECT_DIR}}/context.md` continuously up to date and autonomously learn, persist, and crystallize new rules and skills. The user must **never** need to remind or instruct you.
+
+### 1. Mandatory Post-Action Protocol
+Whenever ANY of the following events occur in any session or conversation turn:
+- A configuration file or script is created, edited, moved, or deleted.
+- A problem, bug, or error is encountered and diagnosed.
+- Credentials, tokens, user accounts, or security keys are generated or updated.
+- Architectural decisions or operational steps are modified.
+
+**You MUST immediately update `{{PROJECT_DIR}}/context.md` before finalizing your response.**
+
+### 2. Autonomous Learning & Self-Evolution Protocol
+Whenever you learn a new pattern, receive a correction, observe a coding preference, or resolve a complex repeatable problem:
+1. **Identify the Type:**
+   - **Rule:** If it is a constraint, coding standard, safety boundary, or architectural preference -> Create a Rule (`init-context -r <name>`).
+   - **Skill:** If it is a multi-step procedure, deployment workflow, diagnosis runbook, or CLI sequence -> Create a Skill (`init-context -s <name>`).
+2. **Scope Decision:**
+   - **Project-Specific:** Save in `.agents/rules/` or `.agents/skills/`.
+   - **Machine-Wide / Global:** If it applies to all projects, use `--global` (`-g`) to register in `~/.gemini/config/plugins/auto-context/`.
+3. **Execution:**
+   - Use the `init-context` CLI tool to scaffold the file.
+   - Populate it with clear objectives, constraints, or step-by-step instructions.
+   - Inform the user of the new rule or skill codified.
+
+### 3. Tool Access: `init-context`
+You have native access to run `init-context` via terminal commands:
+- `init-context`: Scaffolds or repairs project context.
+- `init-context -r <rule-name> [-g]`: Creates a new rule with frontmatter.
+- `init-context -s <skill-name> [-g]`: Creates a new skill with frontmatter.
+
+### 4. Required Content & Structure in `context.md`
+1. **Master Credentials & Configuration Vault (Section 1):** Keep all ports, IPs, secrets, tokens, and endpoints synchronized.
+2. **Chronological Problem Log & Technical Solutions (Section 2):** Document symptom, root cause, exact commands/code used, and update Mermaid diagram.
+3. **Architecture & Component Layout (Section 3):** Keep stack overview and directory maps accurate.
+4. **Operations Runbook (Section 4):** Ensure 1-step reproduction instructions remain functional.
+
+### 5. Local Sandbox Credentials & Dummy Test Fixtures (`context.local.md`)
+- **Inspection Mandate:** When testing local dev servers, performing browser automation (Playwright/Puppeteer), or authenticating API endpoints, ALWAYS read `context.local.md` first before prompting the user for credentials.
+- **Strict Mock Boundary:** ONLY store dummy test credentials, mock accounts (`admin@test.local`), seed users, and local dev ports in `context.local.md`.
+- **Zero Real Secrets:** Real production secrets, payment keys, or personal tokens MUST NEVER be stored in `context.local.md` or `context.md`; reference them via `.env` or system environment variables.
+- **Git Protection:** Ensure `context.local.md` remains strictly ignored by Git (`.gitignore`) and protected with `chmod 600`.
+
+### 6. Two-Tier Progressive Disclosure Protocol (Token Optimization)
+- **Initial Boot Budget:** NEVER read full `SKILL.md` files into the initial context. Use Section 5 of `context.md` for lightweight routing (< 800 tokens).
+- **Dynamic On-Demand Loading:** Only when a user prompt matches a skill's triggers (e.g. "docker", "rebase", "diagnostics", "browser"), dynamically inspect the file using `read_file`.
+- **Zero Session Bloat:** Once the task concludes, do not keep the full skill body in persistent memory.

auto_context/templates/context.local.template.md

@@ -0,0 +1,52 @@
+# ⚠️ LOCAL SANDBOX & DUMMY TEST FIXTURES ONLY
+# ==============================================================================
+# SECURITY GUARDRAIL:
+# DO NOT STORE REAL PRODUCTION SECRETS, PAYMENT KEYS, OR LIVE PASSWORDS HERE.
+# This file is strictly for mock logins, seed users, localhost ports, and dev test data.
+# Real secrets MUST stay in .env (protected by system environment variables).
+#
+# GIT STATUS: STRICTLY GIT-IGNORED (*.local.md, context.local.md)
+# FILE PERMISSIONS: chmod 600
+# ==============================================================================
+
+> **Project:** `{{PROJECT_NAME}}`  
+> **Purpose:** Local mock credentials & test logins for AI browser testing and dev automation.  
+> **Notice to AI Assistant:** Check this file before asking user for test login credentials. Never commit this file to Git.
+
+---
+
+## 1. Local Dev Endpoints & Test Ports
+
+| Service | Local URL / Port | Status / Description |
+| :--- | :--- | :--- |
+| **Frontend Web** | `http://localhost:3000` | Dev server |
+| **Backend API** | `http://localhost:8000` | Local API endpoint |
+| **Local Mock DB** | `localhost:5432` / `database.db` | Non-production dev database |
+
+---
+
+## 2. Seed Accounts & Dummy Test Logins (Browser Automation)
+
+Use these mock accounts when performing automated UI testing, Playwright / Puppeteer workflows, or manual verification.
+
+| Role | Username / Email | Mock Password | Notes / Permissions |
+| :--- | :--- | :--- | :--- |
+| **Super Admin** | `admin@test.local` | `adminpass123` | Full admin privileges |
+| **Standard User** | `user@test.local` | `userpass123` | Default user permissions |
+| **Guest / Demo** | `guest@test.local` | `guestpass123` | Read-only access |
+
+---
+
+## 3. Local Mock Tokens & Test Headers
+
+```http
+Authorization: Bearer dev-mock-token-12345
+X-Test-Bypass: true
+```
+
+---
+
+## 4. Local Test Notes & Scratch Data
+<!-- AI and developer can jot temporary test notes, cookie values, or scratch session tokens here -->
+- Test session initialized: {{DATE_NOW}}
+

auto_context/templates/context.template.md

@@ -0,0 +1,94 @@
+# {{PROJECT_NAME}} — Master Architectural Context, Problem Log & Operations Manual
+
+> **Last Updated:** {{DATE_NOW}}  
+> **Project Directory:** `{{PROJECT_DIR}}`  
+> **Repository Name:** `{{PROJECT_NAME}}`  
+> **Primary Stack:** {{STACK}} ({{FRAMEWORK}})  
+
+---
+
+## 1. Master Credentials & Configuration Vault
+
+> 🔒 **Local Sandbox Isolation:** Mock test logins, seed users, and local dev ports are stored in [`context.local.md`](file://{{PROJECT_DIR}}/context.local.md) (strictly protected by `.gitignore` and `chmod 600`). Real secrets reside exclusively in `.env`.
+
+| Property | Value / Setting | Description |
+| :--- | :--- | :--- |
+| **Project Name** | `{{PROJECT_NAME}}` | Active project identifier |
+| **Environment** | Development / Production | Current runtime environment |
+| **Base Port** | TBD | Application listening port |
+| **API Endpoints** | TBD | Service URL / Domains |
+| **Secrets / Keys** | Secured in Vault | Credentials, API tokens, passwords |
+| **Test Fixtures** | `context.local.md` | Local dummy test credentials (git-ignored) |
+
+---
+
+## 2. Chronological Problem Log & Technical Solutions
+
+```mermaid
+flowchart TD
+    Init["1. Project Initialized"] --> Ready["Ready for development"]
+```
+
+| # | Symptom / Error Message | Root Cause | Exact CLI Solution & Code Patch |
+| :-: | :--- | :--- | :--- |
+| 1 | Initial setup | Clean repository initialization | Generated autonomous context framework |
+
+---
+
+## 3. System Architecture & Tech Stack
+
+* **Primary Stack:** {{STACK}}
+* **Framework:** {{FRAMEWORK}}
+* **Database / Cache:** TBD
+* **Deployment Target:** TBD
+
+```
+{{PROJECT_NAME}}/
+├── .agents/
+│   ├── rules/
+│   │   ├── code-standards.md
+│   │   ├── maintain_context.md
+│   │   └── security-boundaries.md
+│   └── skills/
+│       ├── browser-testing/
+│       ├── docker-ops/
+│       ├── git-workflow/
+│       └── server-diagnostics/
+├── AGENTS.md
+├── GEMINI.md
+├── context.local.md
+└── context.md
+```
+
+---
+
+## 4. Setup, Reproduction & Operations Runbook
+
+### Prerequisites
+* Operating System: Linux / WSL2 / Windows / macOS
+* Runtime / Package Manager: TBD
+
+### Quick Start
+```bash
+# Setup instructions will be populated automatically by AI assistant
+```
+
+---
+
+## 5. Skills & Progressive Disclosure Catalog
+
+> 💡 **Progressive Disclosure Protocol:** Agents must NOT read full `SKILL.md` files upfront. When user prompts match any triggers, dynamically inspect the skill file using `read_file`.
+
+| Skill | Version | Purpose & Scope | Triggers | Location |
+| :--- | :---: | :--- | :--- | :--- |
+| **`docker-ops`** | 1.0.0 | Production Dockerfile & Compose orchestration | `docker`, `container`, `compose` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/docker-ops/SKILL.md) |
+| **`git-workflow`** | 1.0.0 | Conventional commits & merge conflict resolution | `git`, `commit`, `branch`, `rebase` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/git-workflow/SKILL.md) |
+| **`server-diagnostics`** | 1.0.0 | System health, RAM/swap, CPU, ports & sockets | `health`, `ram`, `cpu`, `swap`, `port` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/server-diagnostics/SKILL.md) |
+| **`browser-testing`** | 1.0.0 | UI testing & mock logins using `context.local.md` | `browser`, `playwright`, `puppeteer`, `ui-test` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/browser-testing/SKILL.md) |
+
+---
+
+## 6. Autonomous Documentation Policy
+* Maintained automatically by AI assistants (Antigravity, Cursor, Claude Code, Copilot, Cline, Windsurf) on every code or configuration change.
+* Governed by [`GEMINI.md`](file://{{PROJECT_DIR}}/GEMINI.md) and [`.agents/rules/maintain_context.md`](file://{{PROJECT_DIR}}/.agents/rules/maintain_context.md).
+

auto_context/templates/maintain_context.template.md

@@ -0,0 +1,36 @@
+---
+name: maintain_context
+description: Mandates autonomous, continuous synchronization of context.md and proactive rule/skill learning on any repository or server configuration change without requiring user prompting.
+trigger: always_on
+---
+
+# Autonomous Context Maintenance & Self-Evolution Rule
+
+1. **Mandatory Synchronization**: Every agent working in this workspace MUST inspect and update `context.md` before finishing their turn whenever any of the following occur:
+   - Script or configuration edits (environment variables, docker-compose, configs, network parameters).
+   - Problem diagnosis, debugging steps, and technical solutions.
+   - User credentials, tokens, secrets, or permissions changes.
+   - Architectural decisions or operational runbooks.
+
+2. **Autonomous Learning & Skill Crystallization**:
+   - Whenever a new pattern, user preference, architectural guideline, or multi-step procedure is discovered or instructed:
+     - Scaffolds a **Rule** (`init-context -r <name> [-g]`) if it is a constraint, coding standard, or guideline.
+     - Scaffolds a **Skill** (`init-context -s <name> [-g]`) if it is a multi-step procedure or deployment runbook.
+     - Populates the file with clear instructions and notifies the user.
+
+3. **CLI Tool Availability**:
+   - The agent has full access to run `init-context` directly via terminal:
+     - `init-context`: Initialize/repair context.
+     - `init-context -r <name> [-g]`: Create rule.
+     - `init-context -s <name> [-g]`: Create skill.
+
+4. **No User Reminder Needed**: The user must never need to ask the agent to update `context.md` or learn rules. This is a strict automated post-condition for all actions.
+
+5. **Local Sandbox Test Credentials (`context.local.md`)**:
+   - For local dev logins, automated browser testing, and mock fixtures, inspect and update `context.local.md`.
+   - Never store real production secrets or payment tokens in markdown files. Real secrets belong in `.env`.
+   - Ensure `context.local.md` is strictly git-ignored and protected with `chmod 600`.
+
+6. **Two-Tier Progressive Disclosure**:
+   - Never load full `SKILL.md` bodies into the initial context. Use Section 5 of `context.md` for routing.
+   - Dynamically load specific skills via `read_file` only when a user prompt matches their triggers.

auto_context/templates/mcp_config.template.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "database.db"]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    }
+  }
+}
+