ragtime-cli 0.2.1__tar.gz → 0.2.3__tar.gz

{ragtime_cli-0.2.1/ragtime_cli.egg-info → ragtime_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.1
+Version: 0.2.3
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT

{ragtime_cli-0.2.1 → ragtime_cli-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragtime-cli"
-version = "0.2.1"
+version = "0.2.3"
 description = "Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge"
 readme = "README.md"
 license = "MIT"

{ragtime_cli-0.2.1 → ragtime_cli-0.2.3/ragtime_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.1
+Version: 0.2.3
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT

{ragtime_cli-0.2.1 → ragtime_cli-0.2.3}/ragtime_cli.egg-info/SOURCES.txt

@@ -14,7 +14,9 @@ src/db.py
 src/mcp_server.py
 src/memory.py
 src/commands/audit.md
+src/commands/create-pr.md
 src/commands/handoff.md
+src/commands/import-docs.md
 src/commands/pr-graduate.md
 src/commands/recall.md
 src/commands/remember.md

{ragtime_cli-0.2.1 → ragtime_cli-0.2.3}/src/cli.py

@@ -166,7 +166,7 @@ def get_remote_branches_with_ragtime(path: Path) -> list[str]:
 
 
 @click.group()
-@click.version_option(version="0.2.1")
+@click.version_option(version="0.2.3")
 def main():
     """Ragtime - semantic search over code and documentation."""
     pass
@@ -206,11 +206,45 @@ index/
 """
     gitignore_path.write_text(gitignore_content)
 
+    # Create conventions file template
+    conventions_file = ragtime_dir / "CONVENTIONS.md"
+    if not conventions_file.exists():
+        conventions_file.write_text("""# Team Conventions
+
+Rules and patterns that code must follow. These are checked by `/create-pr`.
+
+## Code Style
+
+- [ ] Example: Use async/await, not .then() chains
+- [ ] Example: All API endpoints must use auth middleware
+
+## Architecture
+
+- [ ] Example: Services should not directly access repositories from other domains
+
+## Security
+
+- [ ] Example: Never commit .env or credentials files
+- [ ] Example: All user input must be validated
+
+## Testing
+
+- [ ] Example: All new features need unit tests
+
+---
+
+Add your team's conventions above. Each rule should be:
+- Clear and specific
+- Checkable against code
+- Actionable (what to do, not just what not to do)
+""")
+
     click.echo(f"\nCreated .ragtime/ structure:")
-    click.echo(f"  app/       - Graduated knowledge (tracked)")
-    click.echo(f"  team/      - Team conventions (tracked)")
-    click.echo(f"  branches/  - Active branches (yours tracked, synced gitignored)")
-    click.echo(f"  archive/   - Completed branches (tracked)")
+    click.echo(f"  app/           - Graduated knowledge (tracked)")
+    click.echo(f"  team/          - Team conventions (tracked)")
+    click.echo(f"  branches/      - Active branches (yours tracked, synced gitignored)")
+    click.echo(f"  archive/       - Completed branches (tracked)")
+    click.echo(f"  CONVENTIONS.md - Team rules checked by /create-pr")
 
     # Check for ghp-cli
     if check_ghp_installed():
@@ -362,6 +396,9 @@ def config(path: Path):
     click.echo(f"  Paths: {cfg.code.paths}")
     click.echo(f"  Languages: {cfg.code.languages}")
     click.echo(f"  Exclude: {cfg.code.exclude}")
+    click.echo("\nConventions:")
+    click.echo(f"  Files: {cfg.conventions.files}")
+    click.echo(f"  Also search memories: {cfg.conventions.also_search_memories}")
 
 
 # ============================================================================
@@ -709,21 +746,54 @@ def install_commands(global_install: bool, workspace_install: bool, list_command
     target_dir.mkdir(parents=True, exist_ok=True)
     commands_dir = get_commands_dir()
     installed = 0
+    skipped = 0
+    namespaced = 0
 
     for cmd in to_install:
         source = commands_dir / f"{cmd}.md"
         target = target_dir / f"{cmd}.md"
+        namespaced_target = target_dir / f"ragtime-{cmd}.md"
 
         if target.exists() and not force:
-            if click.confirm(f"  {cmd}.md exists. Overwrite?", default=False):
+            # Check if it's our file (contains ragtime marker)
+            existing_content = target.read_text()
+            is_ragtime_file = "ragtime" in existing_content.lower() and "mcp__ragtime" in existing_content
+
+            if is_ragtime_file:
+                # It's our file, safe to overwrite
                 target.write_text(source.read_text())
+                click.echo(f"  ✓ {cmd}.md (updated)")
                 installed += 1
+            else:
+                # Conflict with non-ragtime command
+                click.echo(f"\n⚠️  Conflict: {cmd}.md already exists (not a ragtime command)")
+                click.echo(f"   1. Overwrite with ragtime's version")
+                click.echo(f"   2. Skip (keep existing)")
+                click.echo(f"   3. Install as ragtime-{cmd}.md")
+
+                choice = click.prompt("   Choice", type=click.Choice(["1", "2", "3"]), default="2")
+
+                if choice == "1":
+                    target.write_text(source.read_text())
+                    click.echo(f"  ✓ {cmd}.md (overwritten)")
+                    installed += 1
+                elif choice == "2":
+                    click.echo(f"  • {cmd}.md (skipped)")
+                    skipped += 1
+                else:
+                    namespaced_target.write_text(source.read_text())
+                    click.echo(f"  ✓ ragtime-{cmd}.md")
+                    namespaced += 1
         else:
             target.write_text(source.read_text())
             click.echo(f"  ✓ {cmd}.md")
             installed += 1
 
     click.echo(f"\nInstalled {installed} commands to {target_dir}")
+    if namespaced:
+        click.echo(f"  ({namespaced} installed with ragtime- prefix)")
+    if skipped:
+        click.echo(f"  ({skipped} skipped due to conflicts)")
 
 
 @main.command("setup-ghp")
@@ -1105,6 +1175,193 @@ def daemon_status(path: Path):
         pid_file.unlink()
 
 
+@main.command()
+@click.argument("docs_path", type=click.Path(exists=True, path_type=Path), default="docs")
+@click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
+@click.option("--fix", is_flag=True, help="Interactively add frontmatter to files")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def audit(docs_path: Path, path: Path, fix: bool, as_json: bool):
+    """Audit docs for ragtime-compatible frontmatter.
+
+    Scans markdown files and suggests metadata for better indexing.
+
+    Examples:
+        ragtime audit docs/              # Audit docs folder
+        ragtime audit docs/ --fix        # Interactively add frontmatter
+        ragtime audit . --json           # Output suggestions as JSON
+    """
+    import re
+    import json as json_module
+
+    path = Path(path).resolve()
+    docs_path = Path(docs_path).resolve()
+
+    if not docs_path.exists():
+        click.echo(f"✗ Path not found: {docs_path}", err=True)
+        return
+
+    # Find all markdown files
+    md_files = list(docs_path.rglob("*.md"))
+
+    if not md_files:
+        click.echo(f"No markdown files found in {docs_path}")
+        return
+
+    results = []
+
+    for md_file in md_files:
+        content = md_file.read_text()
+        relative = md_file.relative_to(path) if md_file.is_relative_to(path) else md_file
+
+        # Check for existing frontmatter
+        has_frontmatter = content.startswith("---")
+        existing_meta = {}
+
+        if has_frontmatter:
+            try:
+                import yaml
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    existing_meta = yaml.safe_load(parts[1]) or {}
+            except:
+                pass
+
+        # Analyze file for suggestions
+        suggestions = analyze_doc_for_metadata(md_file, content, existing_meta)
+
+        status = "ok" if not suggestions["missing"] else "needs_update"
+        if not has_frontmatter:
+            status = "no_frontmatter"
+
+        results.append({
+            "file": str(relative),
+            "status": status,
+            "has_frontmatter": has_frontmatter,
+            "existing": existing_meta,
+            "suggestions": suggestions,
+        })
+
+    if as_json:
+        click.echo(json_module.dumps(results, indent=2))
+        return
+
+    # Summary
+    no_fm = [r for r in results if r["status"] == "no_frontmatter"]
+    needs_update = [r for r in results if r["status"] == "needs_update"]
+    ok = [r for r in results if r["status"] == "ok"]
+
+    click.echo(f"\nAudited {len(md_files)} files in {docs_path.name}/\n")
+
+    if ok:
+        click.echo(f"✓ {len(ok)} files have complete frontmatter")
+
+    if needs_update:
+        click.echo(f"• {len(needs_update)} files could use more metadata")
+
+    if no_fm:
+        click.echo(f"✗ {len(no_fm)} files have no frontmatter\n")
+
+        for r in no_fm[:10]:  # Show first 10
+            click.echo(f"{'─' * 60}")
+            click.echo(f"  {r['file']}")
+            s = r["suggestions"]
+            click.echo(f"  Suggested frontmatter:")
+            click.echo(f"    namespace: {s.get('namespace', 'app')}")
+            click.echo(f"    type: {s.get('type', 'document')}")
+            if s.get("component"):
+                click.echo(f"    component: {s['component']}")
+
+        if len(no_fm) > 10:
+            click.echo(f"\n  ... and {len(no_fm) - 10} more files")
+
+    if fix and no_fm:
+        click.echo(f"\n{'─' * 60}")
+        if click.confirm(f"\nAdd frontmatter to {len(no_fm)} files?"):
+            added = 0
+            for r in no_fm:
+                file_path = path / r["file"]
+                content = file_path.read_text()
+                s = r["suggestions"]
+
+                # Build frontmatter
+                fm_lines = ["---"]
+                fm_lines.append(f"namespace: {s.get('namespace', 'app')}")
+                fm_lines.append(f"type: {s.get('type', 'document')}")
+                if s.get("component"):
+                    fm_lines.append(f"component: {s['component']}")
+                fm_lines.append("---")
+                fm_lines.append("")
+
+                new_content = "\n".join(fm_lines) + content
+                file_path.write_text(new_content)
+                added += 1
+                click.echo(f"  ✓ {r['file']}")
+
+            click.echo(f"\n✓ Added frontmatter to {added} files")
+            click.echo(f"  Run 'ragtime reindex' to update the search index")
+
+
+def analyze_doc_for_metadata(file_path: Path, content: str, existing: dict) -> dict:
+    """Analyze a document and suggest metadata."""
+    import re
+
+    suggestions = {}
+    missing = []
+
+    # Infer from path
+    parts = file_path.parts
+    path_lower = str(file_path).lower()
+
+    # Namespace inference
+    if "namespace" not in existing:
+        missing.append("namespace")
+        if ".ragtime" in path_lower or "memory" in path_lower:
+            suggestions["namespace"] = "app"
+        elif "team" in path_lower or "convention" in path_lower:
+            suggestions["namespace"] = "team"
+        else:
+            suggestions["namespace"] = "app"
+
+    # Type inference
+    if "type" not in existing:
+        missing.append("type")
+
+        # Check content for clues
+        content_lower = content.lower()
+
+        if "api" in path_lower or "endpoint" in content_lower:
+            suggestions["type"] = "architecture"
+        elif "decision" in path_lower or "adr" in path_lower or "we decided" in content_lower:
+            suggestions["type"] = "decision"
+        elif "guide" in path_lower or "how to" in content_lower:
+            suggestions["type"] = "pattern"
+        elif "setup" in path_lower or "install" in path_lower:
+            suggestions["type"] = "convention"
+        elif "readme" in path_lower:
+            suggestions["type"] = "document"
+        elif "changelog" in path_lower or "release" in path_lower:
+            suggestions["type"] = "document"
+        else:
+            suggestions["type"] = "document"
+
+    # Component inference from path
+    if "component" not in existing:
+        # Look for component-like folder names
+        component_candidates = []
+        skip = {"docs", "src", "lib", "app", "pages", "components", "memory", ".ragtime"}
+
+        for part in parts[:-1]:  # Exclude filename
+            if part.lower() not in skip and not part.startswith("."):
+                component_candidates.append(part.lower())
+
+        if component_candidates:
+            suggestions["component"] = component_candidates[-1]  # Most specific
+            missing.append("component")
+
+    suggestions["missing"] = missing
+    return suggestions
+
+
 @main.command()
 @click.option("--check", is_flag=True, help="Only check for updates, don't install")
 def update(check: bool):
@@ -1113,7 +1370,7 @@ def update(check: bool):
     from urllib.request import urlopen
     from urllib.error import URLError
 
-    current = "0.2.1"
+    current = "0.2.3"
 
     click.echo(f"Current version: {current}")
     click.echo("Checking PyPI for updates...")

ragtime_cli-0.2.3/src/commands/create-pr.md

@@ -0,0 +1,389 @@
+---
+description: Create a PR with convention checks and graduated knowledge
+allowed-arguments: optional PR title
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion, mcp__ragtime__search, mcp__ragtime__memories
+---
+
+# Create PR
+
+Create a pull request with branch knowledge graduated and committed alongside the code.
+
+**Usage:**
+- `/create-pr` - Interactive PR creation with memory curation
+- `/create-pr "Add authentication flow"` - With suggested title
+
+## Overview
+
+This command ensures code follows team standards and knowledge gets merged with the code:
+
+1. Check code against team conventions and app patterns
+2. Review branch memories and decide what graduates to `app/`
+3. Check for conflicts with existing app knowledge
+4. Commit graduated memories as part of the PR
+5. Create the pull request
+
+## Step 1: Gather Context
+
+```bash
+BRANCH=$(git branch --show-current)
+BRANCH_SLUG=$(echo "$BRANCH" | tr '/' '-')
+
+echo "Branch: $BRANCH"
+
+# Check for uncommitted changes
+git status --short
+
+# Get commits on this branch
+git log main..HEAD --oneline
+```
+
+## Step 2: Check Code Against Team Conventions
+
+Before creating the PR, verify the code follows team standards.
+
+### Load conventions config
+
+Check `.ragtime/config.yaml` for conventions settings:
+
+```yaml
+# Default config (if not specified):
+conventions:
+  files:
+    - ".ragtime/CONVENTIONS.md"
+  also_search_memories: true
+```
+
+### Read conventions files
+
+For each file in `conventions.files`, read it if it exists:
+
+```bash
+# Check for conventions files
+cat .ragtime/CONVENTIONS.md 2>/dev/null
+# Or other configured files like docs/CODING_STANDARDS.md
+```
+
+The conventions doc should contain clear, checkable rules like:
+- "All API endpoints must use auth middleware"
+- "Use async/await, not .then() chains"
+- "Never commit .env files"
+
+### Also search memories (if enabled)
+
+If `also_search_memories: true` (default), also search for convention memories:
+
+```
+mcp__ragtime__search:
+  query: "convention standard pattern rule always never"
+  namespace: "team"
+  limit: 20
+```
+
+```
+mcp__ragtime__search:
+  query: "pattern architecture convention"
+  namespace: "app"
+  type: "convention,pattern"
+  limit: 20
+```
+
+### Get changed files
+
+```bash
+# Files changed in this branch
+git diff --name-only main...HEAD
+```
+
+### Review code against conventions
+
+For each relevant convention/pattern found, check if the changed code follows it:
+
+1. Read the convention/pattern memory
+2. Read the relevant changed files
+3. Check for compliance
+
+Present findings:
+
+```
+───────────────────────────────────────────
+🔍 CONVENTION CHECK
+───────────────────────────────────────────
+
+Checked {file_count} changed files against {convention_count} team conventions.
+
+✅ PASSING:
+- "Use async/await, not .then()" - All async code uses await
+- "Error responses use ApiError class" - Verified in api/routes.ts
+
+⚠️ POTENTIAL ISSUES:
+- "All API endpoints need auth middleware"
+  → src/api/newEndpoint.ts:15 - No auth middleware detected
+
+- "Use logger.error(), not console.error()"
+  → src/services/auth.ts:42 - Found console.error()
+
+❌ VIOLATIONS:
+- "Never commit .env files"
+  → .env.local is staged
+───────────────────────────────────────────
+```
+
+### Handle issues
+
+If issues found:
+
+```
+Found {issue_count} potential issues.
+
+Options:
+1. **Fix now** - I'll help fix these before creating PR
+2. **Ignore** - Create PR anyway (add justification comment)
+3. **Review each** - Go through issues one by one
+4. **Cancel** - Fix manually and try again
+```
+
+If "Fix now": Help the user fix each issue before proceeding.
+
+If "Ignore": Ask for justification to include in PR description.
+
+**Only proceed to memory curation after issues are resolved or acknowledged.**
+
+## Step 3: Check for Branch Memories
+
+Search for memories in this branch's namespace:
+
+```bash
+# Check .ragtime/branches/{branch-slug}/ for memory files
+ls -la .ragtime/branches/$BRANCH_SLUG/ 2>/dev/null || echo "No branch memories found"
+```
+
+Also search the index:
+
+```
+mcp__ragtime__search:
+  query: "*"
+  namespace: "branch-{branch-slug}"
+  limit: 50
+```
+
+**If no branch memories found:** Skip to Step 8 (Create PR).
+
+**If memories found:** Continue to Step 4.
+
+## Step 4: Present Memories for Curation
+
+```
+───────────────────────────────────────────
+📋 BRANCH KNOWLEDGE REVIEW
+───────────────────────────────────────────
+
+Before creating the PR, let's review knowledge from this branch.
+
+Graduated memories will be:
+- Moved to app/ or team/ namespace
+- Committed as part of this PR
+- Merged with your code changes
+
+Found {count} memories in branch-{branch}:
+
+───────────────────────────────────────────
+```
+
+For each memory, show:
+
+```
+**Memory {n} of {count}:**
+
+"{content preview - first 150 chars}..."
+
+Type: {type} | Component: {component}
+File: {relative_path}
+
+Action?
+1. ✅ Graduate to app/
+2. 🏛️ Graduate to team/ (conventions/standards)
+3. 📚 Keep in branch (don't include in PR)
+4. ❌ Abandon (mark as noise)
+5. 👀 Show full content
+```
+
+## Step 5: Check for Conflicts
+
+For each memory being graduated, search for similar content in app/:
+
+```
+mcp__ragtime__search:
+  query: "{memory content keywords}"
+  namespace: "app"
+  limit: 5
+```
+
+If similar memories exist (similarity > 0.8), present:
+
+```
+⚠️ POTENTIAL CONFLICT
+
+Graduating: "{new memory preview}..."
+
+Similar existing memory in app/:
+"{existing memory preview}..."
+File: {existing_file}
+
+Options:
+1. **Keep both** - They're different enough
+2. **Replace existing** - New one is better/more current
+3. **Merge** - Combine into one comprehensive memory
+4. **Skip graduation** - Existing one is sufficient
+```
+
+### If merging:
+
+Ask the user to provide the merged content, or offer to draft it:
+
+```
+I can draft a merged version combining both. Want me to try?
+```
+
+If yes, present the draft for approval before saving.
+
+## Step 6: Execute Graduation
+
+For each memory to graduate:
+
+### Move the file
+
+```bash
+# From: .ragtime/branches/{branch-slug}/{id}-{slug}.md
+# To:   .ragtime/app/{component}/{id}-{slug}.md (or .ragtime/team/)
+
+mkdir -p .ragtime/app/{component}
+mv .ragtime/branches/{branch-slug}/{id}-{slug}.md .ragtime/app/{component}/
+```
+
+### Update the frontmatter
+
+Edit the file to update:
+- `namespace: app` (or `team`)
+- `confidence: high`
+- `confidence_reason: pr-graduate`
+- `source: pr-graduate`
+- Add `graduated_from: branch-{branch}`
+
+### Stage the changes
+
+```bash
+git add .ragtime/app/
+git add .ragtime/team/
+# Don't stage branch/ folder - it stays local or gets cleaned up later
+```
+
+## Step 7: Commit Knowledge (if any graduated)
+
+If memories were graduated:
+
+```bash
+git add .ragtime/app/ .ragtime/team/
+
+git commit -m "docs: graduate branch knowledge to app
+
+Graduated {count} memories from branch-{branch}:
+- {memory1 summary}
+- {memory2 summary}
+..."
+```
+
+## Step 8: Create the PR
+
+```bash
+# Check if we need to push
+git push -u origin $BRANCH 2>/dev/null || git push
+
+# Create PR
+gh pr create --title "{title}" --body "$(cat <<'EOF'
+## Summary
+
+{summary from commits and context}
+
+## Convention Compliance
+
+{if all passed}
+✅ All team conventions verified
+
+{if issues were acknowledged}
+⚠️ Known deviations:
+- {issue}: {justification}
+
+## Knowledge Added
+
+{if memories were graduated}
+This PR includes {count} graduated memories:
+- {list of graduated memories with types}
+
+## Test Plan
+
+- [ ] {test items}
+
+---
+🤖 Generated with [Claude Code](https://claude.ai/code)
+EOF
+)"
+```
+
+## Step 9: Summary
+
+```
+───────────────────────────────────────────
+✅ PR CREATED
+───────────────────────────────────────────
+
+PR: {url}
+Branch: {branch}
+
+Knowledge graduated: {count}
+  → app/: {app_count}
+  → team/: {team_count}
+
+Remaining in branch/: {kept_count}
+Abandoned: {abandoned_count}
+
+The graduated knowledge is now part of your PR.
+Reviewers will see it alongside your code changes.
+```
+
+## Quick Mode
+
+For branches with few memories, offer quick mode:
+
+```
+Found {count} branch memories.
+
+1. **Review each** - Curate one by one
+2. **Quick mode** - I'll propose what to graduate
+3. **Graduate all to app/** - Promote everything
+4. **Skip knowledge** - Create PR without graduating
+```
+
+Quick mode analyzes content and proposes:
+
+```
+## Quick Mode Proposal
+
+**Graduate to app/:**
+- "Auth uses JWT with 15-min expiry" (architecture)
+- "Redis chosen for session storage" (decision)
+
+**Keep in branch:**
+- "Debug notes: token refresh" (task-state)
+
+**Abandon:**
+- "TODO: fix later" (noise)
+
+Approve this? (yes / review each / edit)
+```
+
+## Notes
+
+- Graduated memories are committed as part of the PR, so reviewers see them
+- Branch memories that aren't graduated stay in `.ragtime/branches/` for reference
+- After PR merges, run `ragtime prune` to clean up synced branch folders
+- The old `/pr-graduate` command can still be used if you forget to graduate before PR

ragtime_cli-0.2.3/src/commands/import-docs.md

@@ -0,0 +1,259 @@
+---
+description: Migrate existing docs into ragtime memory structure with AI-assisted classification
+allowed-arguments: path to docs folder (e.g., /import-docs docs/)
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# Import Docs
+
+Analyze an existing docs folder and migrate content into the ragtime memory structure.
+
+**Usage:**
+- `/import-docs docs/` - Analyze docs folder and create memories
+- `/import-docs` - Interactive mode, asks for path
+
+## Overview
+
+This command helps teams that have existing documentation migrate into ragtime's structured memory system. It:
+
+1. Scans all markdown files using `ragtime audit --json`
+2. Analyzes each document's content to classify properly
+3. Determines what should become memories vs. stay as indexed docs
+4. Creates memories in `.ragtime/app/` or `.ragtime/team/` as appropriate
+
+## Step 1: Get the Docs Path
+
+**If `$ARGUMENTS` provided:**
+- Use it as the docs path
+
+**If no arguments:**
+- Ask: "What docs folder should I analyze? (e.g., docs/, documentation/)"
+
+## Step 2: Run Audit
+
+Run the ragtime audit command to get a structured view of all docs:
+
+```bash
+ragtime audit {docs_path} --json
+```
+
+Parse the JSON output to get the list of files and initial suggestions.
+
+## Step 3: Analyze Documents
+
+For each document (or batch), read the content and classify:
+
+### Classification Questions
+
+For each doc, determine:
+
+1. **Is this memory-worthy or just reference?**
+   - Memory-worthy: Contains decisions, patterns, architecture insights, conventions
+   - Reference: API docs, changelogs, auto-generated content, raw specs
+
+2. **What type of knowledge is it?**
+   - `architecture` - How systems/components work
+   - `decision` - Why we chose X over Y (look for "we decided", "because", trade-off discussion)
+   - `convention` - Team rules, coding standards, process docs
+   - `pattern` - Reusable solutions, "how to do X"
+   - `integration` - How external services connect
+   - `feature` - Feature documentation
+
+3. **What namespace?**
+   - `app` - Technical knowledge about this codebase
+   - `team` - Team conventions, process, standards
+
+4. **What component?** (infer from path and content)
+
+5. **Should this doc be split?**
+   - Large docs with multiple distinct sections may become multiple memories
+   - Each memory should be focused on ONE concept
+
+### Classification Hints
+
+Look for signals in the content:
+
+| Signal | Likely Type |
+|--------|-------------|
+| "We decided to..." | decision |
+| "Always do X when Y" | convention |
+| "The {system} works by..." | architecture |
+| "To implement X, follow these steps..." | pattern |
+| "Integrates with {service} via..." | integration |
+| ADR format, numbered decisions | decision |
+| API endpoints, request/response | architecture |
+| Setup instructions, onboarding | convention |
+
+## Step 4: Choose Migration Strategy
+
+Ask the user:
+
+```
+How should I handle the original docs?
+
+1. **Memories only** - Create memories in .ragtime/, leave original docs unchanged
+2. **Frontmatter only** - Add frontmatter to original docs for better indexing, no memories
+3. **Both** - Add frontmatter to originals AND create memories for key insights (recommended)
+```
+
+Based on their choice, adjust what the migration plan includes.
+
+## Step 5: Generate Migration Plan
+
+Create a migration plan based on the user's strategy choice:
+
+```
+## Migration Plan
+
+### Will Add Frontmatter (if strategy includes frontmatter)
+
+| File | Namespace | Type | Component |
+|------|-----------|------|-----------|
+| docs/auth/JWT_DESIGN.md | app | architecture | auth |
+| docs/CODING_STANDARDS.md | team | convention | - |
+| ... | | | |
+
+### Will Create Memories (if strategy includes memories)
+
+| File | Type | Namespace | Component | Notes |
+|------|------|-----------|-----------|-------|
+| docs/auth/JWT_DESIGN.md | architecture | app | auth | Split into 2 memories |
+| docs/CODING_STANDARDS.md | convention | team | - | Full doc |
+| ... | | | | |
+
+### Will Index Only (no memory, just frontmatter or skip)
+
+These stay as searchable docs but don't become memories:
+- docs/CHANGELOG.md (reference)
+- docs/api/endpoints.md (reference, auto-generated)
+- ...
+
+### Will Skip (Z files)
+
+- docs/archive/old-stuff.md (outdated)
+- ...
+```
+
+## Step 6: Get Approval
+
+Present the plan and ask:
+
+```
+I've analyzed {total} docs:
+- {X} will become memories in .ragtime/
+- {Y} will be indexed as reference docs
+- {Z} will be skipped
+
+Review the plan above. Should I:
+1. Proceed with all
+2. Let me adjust some classifications
+3. Show me a specific file's analysis
+4. Cancel
+```
+
+## Step 7: Execute Migration
+
+### If adding frontmatter to originals:
+
+For each doc that needs frontmatter, prepend:
+
+```yaml
+---
+namespace: {app|team}
+type: {type}
+component: {if applicable}
+---
+```
+
+This makes the original docs index better with `ragtime index`.
+
+### If creating memories:
+
+1. **Extract the key content** - Don't copy the whole doc verbatim unless it's focused. Extract the essential knowledge.
+
+2. **Write the memory file** to `.ragtime/app/{component}/{id}-{slug}.md` or `.ragtime/team/{id}-{slug}.md`:
+
+```yaml
+---
+id: {8-char-uuid}
+namespace: {app|team}
+type: {type}
+component: {if applicable}
+confidence: medium
+confidence_reason: import-docs
+source: import-docs
+status: active
+added: {today}
+migrated_from: {original-file-path}
+---
+
+{extracted content}
+```
+
+3. **For split documents**, create multiple focused memories with related IDs.
+
+## Step 8: Reindex
+
+After all memories are created:
+
+```bash
+ragtime reindex
+```
+
+## Step 9: Summary
+
+Summarize based on what was done:
+
+```
+## Migration Complete
+
+### Frontmatter Added (if applicable)
+Updated {X} docs with frontmatter for better indexing.
+
+### Memories Created (if applicable)
+Created {Y} memories:
+- {N} architecture in app/
+- {N} conventions in team/
+- {N} decisions in app/
+- ...
+
+Next steps:
+- Run 'ragtime index' to update the search index
+- Review memories with: ragtime memories --namespace app
+- Search with: ragtime search "your query"
+- Edit any misclassified content in .ragtime/ or docs/
+```
+
+## Tips
+
+- **Don't over-migrate**: Not every doc needs to be a memory. Reference docs are fine as indexed content.
+- **Preserve originals**: This creates memories FROM docs, doesn't delete originals.
+- **Review component inference**: The path-based component detection may need adjustment.
+- **Batch by folder**: For large doc sets, consider migrating one folder at a time.
+
+## Example Session
+
+```
+User: /import-docs docs/
+
+Claude: I'll analyze your docs folder...
+
+Running: ragtime audit docs/ --json
+
+Found 45 markdown files. Let me analyze each one...
+
+[Analyzes docs/auth/JWT_DESIGN.md]
+This is an architecture doc about JWT implementation. Key insights:
+- 15-minute access token expiry
+- Refresh token rotation strategy
+- Why we chose asymmetric keys
+
+I'll create 1 memory in app/auth/ for this.
+
+[Continues for other files...]
+
+## Migration Plan
+...
+
+Proceed? (yes/adjust/cancel)
+```

{ragtime_cli-0.2.1 → ragtime_cli-0.2.3}/src/commands/pr-graduate.md

@@ -1,9 +1,14 @@
 ---
-description: Graduate branch knowledge to app after PR merge
+description: Graduate branch knowledge to app after PR merge (fallback)
 allowed-tools: Bash, mcp__ragtime__search, mcp__ragtime__graduate, mcp__ragtime__update_status, mcp__ragtime__remember, AskUserQuestion
 ---
 
-# PR Graduate: Curate Branch Knowledge
+# PR Graduate: Curate Branch Knowledge (Post-Merge)
+
+> **Preferred workflow:** Use `/create-pr` instead - it graduates memories *before*
+> creating the PR so knowledge is committed alongside code.
+>
+> Use this command only if you already merged without graduating.
 
 After a PR is merged, review branch memories and decide what becomes permanent app knowledge.
 

{ragtime_cli-0.2.1 → ragtime_cli-0.2.3}/src/config.py

@@ -36,11 +36,19 @@ class CodeConfig:
     ])
 
 
+@dataclass
+class ConventionsConfig:
+    """Configuration for convention checking."""
+    files: list[str] = field(default_factory=lambda: [".ragtime/CONVENTIONS.md"])
+    also_search_memories: bool = True
+
+
 @dataclass
 class RagtimeConfig:
     """Main ragtime configuration."""
     docs: DocsConfig = field(default_factory=DocsConfig)
     code: CodeConfig = field(default_factory=CodeConfig)
+    conventions: ConventionsConfig = field(default_factory=ConventionsConfig)
 
     @classmethod
     def load(cls, project_path: Path) -> "RagtimeConfig":
@@ -58,6 +66,7 @@ class RagtimeConfig:
 
         docs_data = data.get("docs", {})
         code_data = data.get("code", {})
+        conventions_data = data.get("conventions", {})
 
         return cls(
             docs=DocsConfig(
@@ -70,6 +79,12 @@ class RagtimeConfig:
                 languages=code_data.get("languages", CodeConfig().languages),
                 exclude=code_data.get("exclude", CodeConfig().exclude),
             ),
+            conventions=ConventionsConfig(
+                files=conventions_data.get("files", ConventionsConfig().files),
+                also_search_memories=conventions_data.get(
+                    "also_search_memories", ConventionsConfig().also_search_memories
+                ),
+            ),
         )
 
     def save(self, project_path: Path) -> None:
@@ -89,6 +104,10 @@ class RagtimeConfig:
                 "languages": self.code.languages,
                 "exclude": self.code.exclude,
             },
+            "conventions": {
+                "files": self.conventions.files,
+                "also_search_memories": self.conventions.also_search_memories,
+            },
         }
 
         with open(config_path, "w") as f: