feat: gist-to-repo identity shift with philosophy-first agent experience

TODOS.md

@@ -0,0 +1,7 @@
+# TODOS
+
+## Add philosophy/workflow guidance to MCP tool descriptions
+**What:** Enhance MCP tool descriptions in `routes/mcp.py` to include behavioral guidance (when to create pages, visibility recommendations, titling conventions) alongside the current functional descriptions.
+**Why:** Claude Code (the primary agent path) reads MCP tool descriptions, not `/api/v1/agent-setup`. This is where philosophy guidance has the highest impact on actual agent behavior. Codex review flagged this as higher leverage than the agent-setup endpoint changes.
+**Context:** Currently MCP tool descriptions are functional only (e.g., "Create a new page. Content should be markdown starting with `# Title`."). Philosophy guidance lives in `agent-setup` (for the copy-paste prompt path) but not in MCP (for the native Claude Code path). The `list_pages` MCP tool already returns conventions with AGENTS content, but the tool descriptions themselves don't prime the agent's behavior.
+**Depends on:** Nothing. Can be done independently of the agent-setup philosophy changes.

app.py

@@ -83,7 +83,7 @@ def make_session_permanent():
 _CSP = (
     "default-src 'self'; script-src 'self' https://static.cloudflareinsights.com;"
     " connect-src 'self' https://cloudflareinsights.com; style-src 'self';"
-    " img-src 'self' https://*.fly.storage.tigris.dev"
+    " img-src 'self' blob: https://*.fly.storage.tigris.dev"
 )
 
 

cli/jottit_cli/commands/publish.py

@@ -25,9 +25,9 @@ def _read_content(file, title):
 @click.option("--slug", help="Custom slug for the page")
 @click.option(
     "--visibility",
-    type=click.Choice(["unlisted", "listed", "pinned"]),
+    type=click.Choice(["private", "unlisted", "listed", "pinned"]),
     default=None,
-    help="Page visibility (default: unlisted)",
+    help="Page visibility (default: private)",
 )
 @click.option("--title", help="Page title (prepended as # heading if missing)")
 @click.option(

db.py

@@ -1,5 +1,6 @@
 import hashlib
 import importlib.util
+import json
 import os
 import secrets
 import threading
@@ -577,6 +578,53 @@ def create_api_token(user_id, name):
     return token, row["id"]
 
 
+def get_or_create_api_token(user_id, name):
+    """Return an existing token by name, or create one. Returns (token_str, token_id).
+    token_str is None if the token already existed (value not stored)."""
+    with get_db() as conn:
+        existing = conn.execute(
+            "SELECT id FROM api_tokens WHERE user_id = %s AND name = %s LIMIT 1",
+            (user_id, name),
+        ).fetchone()
+        if existing:
+            return None, existing["id"]
+    return create_api_token(user_id, name)
+
+
+def get_setup_checklist(user_id):
+    """Return checklist status for the getting-started flow."""
+    with get_db() as conn:
+        page_count = conn.execute(
+            "SELECT COUNT(*) AS c FROM pages WHERE user_id = %s",
+            (user_id,),
+        ).fetchone()["c"]
+        token_count = conn.execute(
+            "SELECT COUNT(*) AS c FROM api_tokens WHERE user_id = %s",
+            (user_id,),
+        ).fetchone()["c"]
+        mcp_used = conn.execute(
+            "SELECT EXISTS(SELECT 1 FROM revisions r JOIN pages p ON r.page_id = p.id WHERE p.user_id = %s AND r.source = 'mcp') AS e",
+            (user_id,),
+        ).fetchone()["e"]
+    return {
+        "has_pages": page_count > 0,
+        "has_token": token_count > 0,
+        "has_mcp": bool(mcp_used),
+    }
+
+
+def log_event(user_id, event, metadata=None):
+    try:
+        with get_db() as conn:
+            conn.execute(
+                "INSERT INTO user_events (user_id, event, metadata) VALUES (%s, %s, %s)",
+                (user_id, event, json.dumps(metadata) if metadata else None),
+            )
+            conn.commit()
+    except Exception:
+        pass
+
+
 def get_api_tokens(user_id):
     with get_db() as conn:
         return conn.execute(

migrations/026_add_private_visibility.sql

@@ -0,0 +1,4 @@
+-- Re-add 'private' as a valid visibility state.
+-- Private pages are only visible to their owner.
+-- Lifecycle: private → unlisted → listed → pinned
+-- (Previously removed in migration 018.)

migrations/027_add_user_events.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS user_events (
+    id SERIAL PRIMARY KEY,
+    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+    event TEXT NOT NULL,
+    metadata JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS user_events_user_id_idx ON user_events (user_id);
+CREATE INDEX IF NOT EXISTS user_events_event_idx ON user_events (event, created_at DESC);

routes/__init__.py

@@ -43,7 +43,7 @@
     },
 }
 
-VISIBILITY_OPTIONS = ("unlisted", "listed", "pinned")
+VISIBILITY_OPTIONS = ("private", "unlisted", "listed", "pinned")
 
 
 def _get_subdomain():
@@ -106,6 +106,15 @@ def can_edit(page_meta):
     return is_creator(page_meta)
 
 
+def check_page_visibility(page_meta):
+    """Abort 404 if page is private and current user is not the owner."""
+    if not page_meta:
+        return
+    if page_meta.get("visibility") == "private":
+        if session.get("user_id") != page_meta["user_id"]:
+            abort(404)
+
+
 def send_verification(email, purpose):
     code = create_verification_code(email, purpose)
     send_verification_email(email, code)

routes/admin.py

@@ -1,13 +1,16 @@
 import re
 
-from flask import flash, redirect, render_template, request, session
+from flask import flash, jsonify, redirect, render_template, request, session
 
 from db import (
     check_username_available,
     create_api_token,
     delete_api_token,
     delete_user,
     find_or_create_user,
+    get_or_create_api_token,
+    log_event,
+    set_user_username,
     get_api_tokens,
     get_pages_for_user,
     get_user,
@@ -50,9 +53,6 @@ def signin():
             "signin.html", error="Please enter a valid email address."
         )
 
-    if not user_exists(email):
-        return render_template("signin.html", not_found=True)
-
     send_verification(email, "signin")
     return redirect("/signin/verify")
 
@@ -83,8 +83,10 @@ def signin_verify():
     session["user_id"] = user_id
     user = get_user(user_id)
     if user and user.get("username"):
+        log_event(user_id, "signin")
         return redirect(profile_url(user["username"]))
-    return redirect("/")
+    log_event(user_id, "signup")
+    return redirect("/setup/username")
 
 
 @bp.route("/signout", methods=["POST"])
@@ -93,6 +95,108 @@ def signout():
     return redirect("/")
 
 
+@bp.route("/setup/username", methods=["GET", "POST"])
+def setup_username():
+    user_id = session.get("user_id")
+    if not user_id:
+        return redirect("/signin")
+    user = get_user(user_id)
+    if user and user.get("username"):
+        return redirect(profile_url(user["username"]))
+
+    if request.method == "GET":
+        return render_template("setup_username.html")
+
+    username = request.form.get("username", "").strip().lower()
+    if not username:
+        return render_template("setup_username.html", error="Username is required.")
+    if not valid_username(username):
+        return render_template(
+            "setup_username.html",
+            error="Username must be lowercase letters, numbers, and hyphens only.",
+            username=username,
+        )
+    if username in RESERVED_USERNAMES:
+        return render_template(
+            "setup_username.html",
+            error="That username is reserved.",
+            username=username,
+        )
+    if not check_username_available(username):
+        return render_template(
+            "setup_username.html",
+            error="That username is already taken.",
+            username=username,
+        )
+
+    set_user_username(user_id, username)
+    update_user_settings(user_id, name="", username=username, bio="", license=None)
+    return redirect("/setup/profile")
+
+
+@bp.route("/setup/profile", methods=["GET", "POST"])
+def setup_profile():
+    user_id = session.get("user_id")
+    if not user_id:
+        return redirect("/signin")
+    user = get_user(user_id)
+    if not user or not user.get("username"):
+        return redirect("/setup/username")
+
+    if request.method == "GET":
+        return render_template("setup_profile.html", username=user["username"])
+
+    name = request.form.get("name", "").strip()
+    if name:
+        update_user_settings(
+            user_id, name=name, username=user["username"], bio="", license=None
+        )
+
+    file = request.files.get("avatar")
+    if file and file.filename:
+        error = validate_image(file)
+        if not error:
+            ext = ALLOWED_IMAGE_TYPES[file.content_type]
+            fmt = file.content_type.split("/")[-1].upper()
+            if fmt == "JPG":
+                fmt = "JPEG"
+            cropped = crop_square(file, fmt)
+            key = f"{user_id}/avatar.{ext}"
+            url = upload_image(key, cropped, file.content_type)
+            update_user_avatar(user_id, url)
+
+    return redirect(profile_url(user["username"]))
+
+
+@bp.route("/setup/mcp-config", methods=["POST"])
+def setup_mcp_config():
+    user_id = session.get("user_id")
+    if not user_id:
+        return jsonify({"error": "Unauthorized"}), 401
+    user = get_user(user_id)
+    if not user:
+        return jsonify({"error": "Unauthorized"}), 401
+
+    token, token_id = get_or_create_api_token(user_id, "mcp-default")
+    if token is None:
+        # Token already exists but we can't show the stored value.
+        # Rotate: delete old, create new.
+        delete_api_token(token_id, user_id)
+        token, _ = create_api_token(user_id, "mcp-default")
+
+    base_url = request.url_root.rstrip("/")
+    prompt = (
+        f"You are connected to my Jottit, a place where ideas become "
+        f"beautiful pages on the web. When I share an insight worth keeping, "
+        f"capture it as a page. "
+        f"Fetch {base_url}/api/v1/agent-setup with the header "
+        f"'Authorization: Bearer {token}' for API details and my conventions. "
+        f"Then list my pages to understand what's already there."
+    )
+    log_event(user_id, "token_generated")
+    return jsonify({"config_text": prompt})
+
+
 @bp.route("/pages")
 def user_pages():
     from routes.public import _build_page_item, sidebar_vars, compute_initials
@@ -362,6 +466,15 @@ def settings_delete():
     return redirect("/")
 
 
+@bp.route("/settings/mcp")
+def settings_mcp():
+    user_id, user = require_user()
+    if not user:
+        return redirect("/signin")
+    base_url = request.url_root.rstrip("/")
+    return render_template("settings_mcp.html", user=user, base_url=base_url)
+
+
 @bp.route("/settings/tokens", methods=["GET", "POST"])
 @limiter.limit("5 per 5 minutes", methods=["POST"])
 def settings_tokens():

routes/api.py

@@ -59,6 +59,89 @@ def _serialize_page(meta, page_data):
     }
 
 
+@api_bp.route("/agent-setup")
+def agent_setup():
+    user = _require_auth()
+    if not user:
+        return _error(
+            "Unauthorized — include your API token as: Authorization: Bearer YOUR_TOKEN",
+            401,
+        )
+    base_url = request.url_root.rstrip("/")
+    username = user.get("username", "")
+    pages = get_pages_for_user(user["id"])
+    return jsonify(
+        {
+            "welcome": f"You are connected to Jottit as @{username}.",
+            "philosophy": (
+                "Jottit turns markdown into beautiful, shareable web pages. "
+                "When someone shares an insight worth keeping, your job is to "
+                "capture it as a well-structured page. Think of yourself as a "
+                "writing partner, not an API client."
+            ),
+            "workflow": {
+                "when_to_create": (
+                    "When the user shares an insight, idea, or piece of thinking "
+                    "that deserves to exist as its own page. Don't create pages "
+                    "for trivial exchanges."
+                ),
+                "when_to_update": (
+                    "When the user refines or adds to an existing topic. Check "
+                    "list_pages first to avoid duplicates."
+                ),
+                "default_visibility": "private",
+                "titling": (
+                    "Every page starts with a markdown H1 (# Title). Use clear, "
+                    "descriptive titles. The title becomes the page's identity."
+                ),
+                "content_style": (
+                    "Write in clean markdown. The output will be rendered with "
+                    "beautiful typography. No need for HTML."
+                ),
+            },
+            "conventions": build_conventions(pages),
+            "about": "Jottit is a markdown publishing tool. Pages are written in markdown and get a beautiful URL.",
+            "api_base": f"{base_url}/api/v1",
+            "your_profile": f"{base_url}/@{username}",
+            "endpoints": {
+                "list_pages": {
+                    "method": "GET",
+                    "path": "/pages",
+                    "description": "List all your pages. Returns slug, title, visibility, and updated_at.",
+                },
+                "create_page": {
+                    "method": "POST",
+                    "path": "/pages",
+                    "description": "Create a new page.",
+                    "body": {
+                        "content": "# Title\\n\\nMarkdown content here.",
+                        "slug": "(optional)",
+                        "visibility": "(optional: private, unlisted, listed, pinned)",
+                    },
+                },
+                "get_page": {
+                    "method": "GET",
+                    "path": "/pages/{slug}",
+                    "description": "Get a page by slug. Returns title, content (markdown), visibility, and updated_at.",
+                },
+                "update_page": {
+                    "method": "PUT",
+                    "path": "/pages/{slug}",
+                    "description": "Update a page. Send content and/or visibility.",
+                    "body": {
+                        "content": "(optional) full markdown",
+                        "visibility": "(optional)",
+                    },
+                },
+            },
+            "auth": "Include your token in every request: Authorization: Bearer YOUR_TOKEN",
+            "content_format": "All content is markdown. Start with '# Title' on the first line.",
+            "default_visibility": "New pages are private by default. Change to 'listed' to show on your profile.",
+            "try_it": f"To verify this works, call GET {base_url}/api/v1/pages to list your pages.",
+        }
+    )
+
+
 @api_bp.route("/user")
 def get_current_user():
     user = _require_auth()
@@ -155,7 +238,7 @@ def create_page():
         slug = slugify(data.get("slug", "")) or generate_slug()
 
     if user:
-        visibility = data.get("visibility", "unlisted")
+        visibility = data.get("visibility", "private")
         if visibility not in VISIBILITY_OPTIONS:
             return _error(
                 f"Visibility must be one of: {', '.join(VISIBILITY_OPTIONS)}", 400