trying dedicated GH README

.github/README.md

@@ -0,0 +1,59 @@
+# Aileen 3 Core
+## Introduction
+Large Language Models (LLMs) rely on **tools** - sometimes provided by **MCP servers** - to interact with the outside world. Aileen 3 Core is an MCP server that advances the goals of **Information Foraging**: mining for novel insights from high-noise sources to create dense briefings for time efficient consumption by the user.
+
+### Competition submission
+Aileen 3 Core is [a contender](https://huggingface.co/spaces/ndurner/aileen3-core) in the [MCP's 1st Birthday - Hosted by Anthropic and Gradio](https://huggingface.co/MCP-1st-Birthday) hackathon. [Aileen 3 Agent](https://github.com/ndurner/aileen3-agent), an agentic system built on this MCP server, is a [capstone project](https://ndurner.de/links/aileen3-kaggle-writeup) to the [AI Agents Intensive Course with Google](https://www.kaggle.com/learn-guide/5-day-agents).
+
+## Using
+### Using in Claude Desktop
+#### Installing
+1. Optionally, create a new Python virtual environment
+  * example: `python3 -m venv .venv-claude`
+2. Install the Aileen MCP: `pip install ./mcp`
+  * (or `pip install -e ./mcp` if you want to make live changes to this source tree)
+3. Obtain Google Gemini API key: [https://aistudio.google.com](../Google AI Studio)
+3. Add reference to `claude_desktop_config.json`. The Gemini API key will be read from the environment, so can be set here:
+```
+{
+...
+  "mcpServers": {
+    "aileen3-mcp": {
+      "command": "/Users/.../aileen3-core/.venv-claude/bin/python",
+      "args": [
+        "-m",
+        "aileen3_mcp.server"
+      ],
+      "env": {
+        "GEMINI_API_KEY": "AI..."
+      }
+    }
+  }
+}
+```
+4. Restart Claude
+
+#### Using the MCP server
+The model Haiku 4.5 is sufficient for basic tasks. To make your plans fully transparent to the LLM, refer to "aileen3" explicitely in the prompt, e.g.:
+> Use aileen3 to translate slide 3 from YouTube video reference eXP-PvKcI9A to German.
+
+![Screenshot of Claude Desktop: slide translation with Aileen 3 Core](../readme-assets/claude-slide-translation.webp)
+
+#### Debugging
+The message exchange and Claude-facing error messages can be read from Claude log files:
+```
+tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
+```
+
+## Local development
+
+Build and run the Docker Space image locally:
+
+```bash
+docker build -t aileen3-core .
+docker run -it -p 7860:7860 aileen3-core
+```
+
+The Docker build passes `--pre` to `pip install` so it can grab the latest Gradio 6 pre-release builds referenced in `demo/requirements.txt` (which currently specifies `gradio>=6.0.0.dev0`).
+
+The blank Gradio 6 demo lives in `demo/app.py`.

.github/generate_welcome_readme.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+
+import argparse
+import os
+from pathlib import Path
+import re
+
+
+FRONTMATTER_BOUNDARY = re.compile(r"^---\s*$")
+MARKDOWN_LINK = re.compile(r"(!?)\[(?P<text>[^\]]*)\]\((?P<target>[^)]+)\)")
+SKIP_PREFIXES = ("http://", "https://", "mailto:", "#")
+
+
+def strip_frontmatter(raw: str) -> str:
+    lines = raw.splitlines()
+    if not lines or not FRONTMATTER_BOUNDARY.match(lines[0]):
+        return raw
+    end_index = None
+    for i in range(1, len(lines)):
+        if FRONTMATTER_BOUNDARY.match(lines[i]):
+            end_index = i
+            break
+    if end_index is None:
+        return raw
+    body_lines = lines[end_index + 1 :]
+    return "\n".join(body_lines).lstrip("\n")
+
+
+def rewrite_links(raw: str, readme_path: Path, output_path: Path) -> str:
+    readme_dir = readme_path.resolve().parent
+    output_dir = output_path.resolve().parent
+
+    def replace(match: re.Match) -> str:
+        bang = match.group(1)
+        text = match.group("text")
+        target = match.group("target").strip()
+
+        if target.startswith(SKIP_PREFIXES) or target.startswith("/"):
+            return match.group(0)
+
+        source_target = (readme_dir / target).resolve()
+        try:
+            new_target = os.path.relpath(source_target, start=output_dir)
+        except ValueError:
+            new_target = target
+
+        return f"{bang}[{text}]({new_target})"
+
+    return MARKDOWN_LINK.sub(replace, raw)
+
+
+def transform(readme_path: Path, output_path: Path) -> None:
+    raw = readme_path.read_text(encoding="utf-8")
+    no_frontmatter = strip_frontmatter(raw)
+    rewritten = rewrite_links(no_frontmatter, readme_path, output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(rewritten, encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Generate a welcome-page-friendly README by stripping frontmatter "
+            "and rewriting relative links."
+        )
+    )
+    parser.add_argument(
+        "--input",
+        type=Path,
+        default=Path("README.md"),
+        help="Source README file (default: README.md)",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path(".github/README.md"),
+        help="Output Markdown file (default: .github/README.md)",
+    )
+    args = parser.parse_args()
+
+    transform(args.input, args.output)
+
+
+if __name__ == "__main__":
+    main()
+