fmind 0.1.0__tar.gz

fmind-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: fmind
+Version: 0.1.0
+Summary: Read Médéric Hurier's (Fmind) portfolio from the terminal.
+Keywords: portfolio,cli,fmind,resume,articles
+Author: Médéric Hurier
+Author-email: Médéric Hurier <contact@fmind.dev>
+License-Expression: MIT
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.9
+Requires-Python: >=3.11
+Project-URL: Homepage, https://www.fmind.dev/
+Project-URL: Source, https://github.com/fmind/cli
+Project-URL: Issues, https://github.com/fmind/cli/issues
+Description-Content-Type: text/markdown
+
+# fmind
+
+Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio from the terminal.
+
+```bash
+uvx fmind whoami
+```
+
+## Why it stays small
+
+Every command renders a document the website already publishes — the portfolio at [`/api/profile`](https://www.fmind.dev/api/profile) and, for `fmind read`, the Markdown source of an article at `/articles/<slug>.md`. Those are the same sources behind the site, the Atom feed, `llms.txt` and the MCP server.
+
+This package therefore carries no copy of the portfolio and needs **no release when the website changes**: new articles, a renewed certification or a new engagement appear on the next run.
+
+Responses are cached under `${XDG_CACHE_HOME:-~/.cache}/fmind/` for one hour, matching the endpoints' own `Cache-Control`. Once a cache exists the CLI also works offline, falling back to the stale copy when the network is unavailable.
+
+## Commands
+
+| Command                     | Shows                                             |
+| --------------------------- | ------------------------------------------------- |
+| `fmind whoami`              | Name, current mission, contact, availability      |
+| `fmind about`               | The biography                                     |
+| `fmind skills`              | Core expertise, laid out like a usage screen      |
+| `fmind work`                | Engagements, current one first                    |
+| `fmind community`           | Ambassador and advisory roles                     |
+| `fmind cert [--verify]`     | Certifications, the PhD, specializations          |
+| `fmind papers`              | The doctorate and the peer-reviewed publications  |
+| `fmind project [--top 6]`   | Open-source repositories and video series         |
+| `fmind sites`               | Interactive tools published alongside the writing |
+| `fmind article [--limit 6]` | The most recent writing                           |
+| `fmind search <query>`      | Articles matching every term, newest first        |
+| `fmind read <slug> [--raw]` | One article, rendered in the terminal             |
+| `fmind hire`                | What can be booked right now                      |
+
+Global options: `--refresh` to bypass the cache, `--json` to emit the raw section, `--no-color` for pipes, `--version`.
+
+### Reading
+
+`fmind search` matches titles, summaries, tags and slugs; terms are ANDed, so each extra word narrows the result. `--tag` restricts to one of the site's own tags.
+
+```bash
+fmind search "agent security"
+fmind search "" --tag MLOps --limit 3
+```
+
+`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. Use `--raw` for the Markdown source.
+
+```bash
+fmind read agentgateway            # resolves to agentgateway-vs-litellm
+fmind read mlops-adventure-continue --raw | glow -
+```
+
+### Piping
+
+`--json` turns every command into a data source, so the portfolio composes with the rest of the shell.
+
+```bash
+fmind --json article --limit 20 | jq -r '.[] | "\(.date[:10])  \(.title)"'
+fmind --json search agent | jq -r '.[].url'
+fmind --json cert --verify | jq -r '.[].title'
+```
+
+## Install
+
+```bash
+uvx fmind whoami       # zero install
+uv tool install fmind  # persistent
+pipx install fmind     # alternative
+```
+
+Point it at another origin with `FMIND_PROFILE_URL` — useful against a local `mise run watch` server of the website:
+
+```bash
+FMIND_PROFILE_URL=http://127.0.0.1:8080/api/profile fmind whoami
+```
+
+Article reads follow the same origin, so one variable moves the whole CLI.
+
+## Development
+
+```bash
+mise install       # install the pinned toolchain
+mise run install   # sync the locked environment and install hooks
+mise run format    # ruff imports and format, dprint
+mise run check     # ruff, ty, actionlint, zizmor, gitleaks
+mise run test      # offline pytest with branch coverage
+mise run smoke     # exercise every command against the live site
+mise run all       # format, check, test, build — the gate CI runs
+```
+
+## License
+
+[MIT](LICENSE) — © 2026 Médéric Hurier (Fmind).

fmind-0.1.0/README.md

@@ -0,0 +1,93 @@
+# fmind
+
+Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio from the terminal.
+
+```bash
+uvx fmind whoami
+```
+
+## Why it stays small
+
+Every command renders a document the website already publishes — the portfolio at [`/api/profile`](https://www.fmind.dev/api/profile) and, for `fmind read`, the Markdown source of an article at `/articles/<slug>.md`. Those are the same sources behind the site, the Atom feed, `llms.txt` and the MCP server.
+
+This package therefore carries no copy of the portfolio and needs **no release when the website changes**: new articles, a renewed certification or a new engagement appear on the next run.
+
+Responses are cached under `${XDG_CACHE_HOME:-~/.cache}/fmind/` for one hour, matching the endpoints' own `Cache-Control`. Once a cache exists the CLI also works offline, falling back to the stale copy when the network is unavailable.
+
+## Commands
+
+| Command                     | Shows                                             |
+| --------------------------- | ------------------------------------------------- |
+| `fmind whoami`              | Name, current mission, contact, availability      |
+| `fmind about`               | The biography                                     |
+| `fmind skills`              | Core expertise, laid out like a usage screen      |
+| `fmind work`                | Engagements, current one first                    |
+| `fmind community`           | Ambassador and advisory roles                     |
+| `fmind cert [--verify]`     | Certifications, the PhD, specializations          |
+| `fmind papers`              | The doctorate and the peer-reviewed publications  |
+| `fmind project [--top 6]`   | Open-source repositories and video series         |
+| `fmind sites`               | Interactive tools published alongside the writing |
+| `fmind article [--limit 6]` | The most recent writing                           |
+| `fmind search <query>`      | Articles matching every term, newest first        |
+| `fmind read <slug> [--raw]` | One article, rendered in the terminal             |
+| `fmind hire`                | What can be booked right now                      |
+
+Global options: `--refresh` to bypass the cache, `--json` to emit the raw section, `--no-color` for pipes, `--version`.
+
+### Reading
+
+`fmind search` matches titles, summaries, tags and slugs; terms are ANDed, so each extra word narrows the result. `--tag` restricts to one of the site's own tags.
+
+```bash
+fmind search "agent security"
+fmind search "" --tag MLOps --limit 3
+```
+
+`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. Use `--raw` for the Markdown source.
+
+```bash
+fmind read agentgateway            # resolves to agentgateway-vs-litellm
+fmind read mlops-adventure-continue --raw | glow -
+```
+
+### Piping
+
+`--json` turns every command into a data source, so the portfolio composes with the rest of the shell.
+
+```bash
+fmind --json article --limit 20 | jq -r '.[] | "\(.date[:10])  \(.title)"'
+fmind --json search agent | jq -r '.[].url'
+fmind --json cert --verify | jq -r '.[].title'
+```
+
+## Install
+
+```bash
+uvx fmind whoami       # zero install
+uv tool install fmind  # persistent
+pipx install fmind     # alternative
+```
+
+Point it at another origin with `FMIND_PROFILE_URL` — useful against a local `mise run watch` server of the website:
+
+```bash
+FMIND_PROFILE_URL=http://127.0.0.1:8080/api/profile fmind whoami
+```
+
+Article reads follow the same origin, so one variable moves the whole CLI.
+
+## Development
+
+```bash
+mise install       # install the pinned toolchain
+mise run install   # sync the locked environment and install hooks
+mise run format    # ruff imports and format, dprint
+mise run check     # ruff, ty, actionlint, zizmor, gitleaks
+mise run test      # offline pytest with branch coverage
+mise run smoke     # exercise every command against the live site
+mise run all       # format, check, test, build — the gate CI runs
+```
+
+## License
+
+[MIT](LICENSE) — © 2026 Médéric Hurier (Fmind).

fmind-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "fmind"
+version = "0.1.0"
+description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = [
+    "portfolio",
+    "cli",
+    "fmind",
+    "resume",
+    "articles",
+]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.15",
+    "rich>=13.9",
+]
+
+[[project.authors]]
+name = "Médéric Hurier"
+email = "contact@fmind.dev"
+
+[project.urls]
+Homepage = "https://www.fmind.dev/"
+Source = "https://github.com/fmind/cli"
+Issues = "https://github.com/fmind/cli/issues"
+
+[project.scripts]
+fmind = "fmind.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+    "ruff>=0.9",
+    "ty>=0.0.1a1",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fmind"
+module-root = "src"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "S",
+    "SIM",
+    "RUF",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers --cov=fmind --cov-branch --cov-fail-under=85"
+testpaths = ["tests"]
+
+[tool.coverage.report]
+exclude_also = [
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]

fmind-0.1.0/pyproject.toml.orig

@@ -0,0 +1,58 @@
+# https://packaging.python.org/en/latest/specifications/pyproject-toml/
+[project]
+name = "fmind"
+version = "0.1.0"
+description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Médéric Hurier", email = "contact@fmind.dev" }]
+requires-python = ">=3.11"
+keywords = ["portfolio", "cli", "fmind", "resume", "articles"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Utilities",
+]
+dependencies = ["typer>=0.15", "rich>=13.9"]
+
+[project.urls]
+Homepage = "https://www.fmind.dev/"
+Source = "https://github.com/fmind/cli"
+Issues = "https://github.com/fmind/cli/issues"
+
+[project.scripts]
+fmind = "fmind.cli:app"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+  "ruff>=0.9",
+  "ty>=0.0.1a1",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "fmind"
+module-root = "src"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "S", "SIM", "RUF"]
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"] # assertions are the point of a test
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers --cov=fmind --cov-branch --cov-fail-under=85"
+testpaths = ["tests"]
+
+[tool.coverage.report]
+exclude_also = ["if __name__ == .__main__.:", "raise NotImplementedError"]

fmind-0.1.0/src/fmind/__init__.py

@@ -0,0 +1,9 @@
+"""Read Médéric Hurier's (Fmind) portfolio from the terminal.
+
+Every command renders https://www.fmind.dev/api/profile, so this package carries
+no copy of its own and needs no release when the website changes.
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

fmind-0.1.0/src/fmind/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m fmind`."""
+
+from fmind.cli import app
+
+if __name__ == "__main__":
+    app()

fmind-0.1.0/src/fmind/api.py

@@ -0,0 +1,157 @@
+"""Fetch and cache the documents published by www.fmind.dev."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, TypeVar
+
+from fmind import __version__
+
+PROFILE_URL = os.environ.get("FMIND_PROFILE_URL", "https://www.fmind.dev/api/profile")
+# The endpoints advertise `public, max-age=3600`; the on-disk copies honour the same window.
+CACHE_TTL_SECONDS = 3600
+TIMEOUT_SECONDS = 15.0
+# Generous next to a ~75 KB profile and ~20 KB articles, but bounded: a hostile or
+# misrouted origin must not be able to fill the cache directory.
+MAX_BYTES = 8 * 1024 * 1024
+USER_AGENT = f"fmind/{__version__} (+https://github.com/fmind/cli)"
+# Slugs reach the URL and the cache path, so only the shape the site actually mints is accepted.
+SLUG_PATTERN = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
+
+T = TypeVar("T")
+
+
+class FmindError(RuntimeError):
+    """A document could not be obtained, or was not the document that was asked for."""
+
+
+def cache_path(*parts: str) -> Path:
+    """Return an on-disk cache location, honouring XDG_CACHE_HOME."""
+    root = os.environ.get("XDG_CACHE_HOME")
+    base = Path(root) if root else Path.home() / ".cache"
+    return base.joinpath("fmind", *parts)
+
+
+def article_url(slug: str, *, profile_url: str = PROFILE_URL) -> str:
+    """Return the Markdown source URL of an article, on the same origin as the profile."""
+    if not SLUG_PATTERN.match(slug):
+        msg = f"not an article slug: {slug!r}"
+        raise FmindError(msg)
+    origin = profile_url.removesuffix("/api/profile").rstrip("/")
+    return f"{origin}/articles/{slug}.md"
+
+
+def _read_cache(path: Path, ttl: int) -> bytes | None:
+    """Return the cached bytes while they are younger than `ttl`; `ttl < 0` accepts any age."""
+    try:
+        age = time.time() - path.stat().st_mtime
+    except OSError:
+        return None
+    if ttl >= 0 and age > ttl:
+        return None
+    try:
+        return path.read_bytes()
+    except OSError:
+        return None
+
+
+def _write_cache(path: Path, payload: bytes) -> None:
+    """Persist a document, ignoring an unwritable cache directory."""
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_bytes(payload)
+        tmp.replace(path)
+    except OSError:
+        pass  # a read-only cache must not break a working command
+
+
+def _download(url: str, accept: str = "application/json") -> bytes:
+    """Fetch a document over HTTP(S) with an explicit timeout and size bound."""
+    if not url.startswith(("https://", "http://")):
+        msg = f"URL must be http(s): {url}"
+        raise FmindError(msg)
+    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, "Accept": accept})  # noqa: S310
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:  # noqa: S310
+            payload = response.read(MAX_BYTES + 1)
+    except urllib.error.HTTPError as error:
+        msg = f"{url} returned HTTP {error.code}"
+        raise FmindError(msg) from error
+    except (urllib.error.URLError, TimeoutError, OSError) as error:
+        msg = f"could not reach {url}: {error}"
+        raise FmindError(msg) from error
+    if len(payload) > MAX_BYTES:
+        msg = f"{url} returned more than {MAX_BYTES} bytes"
+        raise FmindError(msg)
+    return payload
+
+
+def _load(path: Path, url: str, accept: str, parse: Callable[[bytes], T], *, refresh: bool) -> T:
+    """Return a parsed document from the cache or the network.
+
+    A fresh cache wins unless `refresh`. When the network fails — or answers with
+    something that is not the expected document — a stale cache is still served, so
+    the CLI keeps working offline once it has run at least once. Unparseable cached
+    bytes are discarded rather than surfaced.
+    """
+    if not refresh:
+        cached = _read_cache(path, CACHE_TTL_SECONDS)
+        if cached is not None:
+            try:
+                return parse(cached)
+            except FmindError:
+                pass  # a corrupt cache must not break a working command
+    try:
+        payload = _download(url, accept)
+        value = parse(payload)
+    except FmindError:
+        stale = _read_cache(path, -1)
+        if stale is not None:
+            try:
+                return parse(stale)
+            except FmindError:
+                pass
+        raise
+    _write_cache(path, payload)
+    return value
+
+
+def _parse_profile(payload: bytes) -> dict[str, Any]:
+    """Decode the portfolio document, rejecting anything that is not one."""
+    try:
+        document = json.loads(payload)
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        raise FmindError("the profile endpoint did not return JSON") from error
+    if not isinstance(document, dict) or "metadata" not in document:
+        raise FmindError("the profile endpoint did not return a portfolio document")
+    return document
+
+
+def _parse_markdown(payload: bytes) -> str:
+    """Decode an article, rejecting an HTML error page served with a 200."""
+    try:
+        text = payload.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise FmindError("the article was not UTF-8 text") from error
+    if not text.strip() or text.lstrip().startswith("<"):
+        raise FmindError("the article endpoint did not return Markdown")
+    return text
+
+
+def load_profile(*, refresh: bool = False, url: str = PROFILE_URL) -> dict[str, Any]:
+    """Return the portfolio document behind every section command."""
+    return _load(cache_path("profile.json"), url, "application/json", _parse_profile, refresh=refresh)
+
+
+def load_article(slug: str, *, refresh: bool = False, profile_url: str = PROFILE_URL) -> str:
+    """Return the Markdown source of one published article."""
+    url = article_url(slug, profile_url=profile_url)
+    return _load(cache_path("articles", f"{slug}.md"), url, "text/markdown", _parse_markdown, refresh=refresh)

fmind-0.1.0/src/fmind/articles.py

@@ -0,0 +1,48 @@
+"""Select articles from the profile document: newest, matching, or named."""
+
+from __future__ import annotations
+
+from typing import Any
+
+Article = dict[str, Any]
+
+
+def latest(articles: list[Article], *, limit: int) -> list[Article]:
+    """Return the most recently published articles, newest first."""
+    return sorted(articles, key=lambda a: a["date"], reverse=True)[: max(limit, 0)]
+
+
+def _haystack(article: Article) -> str:
+    """Return the searchable text of one article, lower-cased."""
+    fields = [article["title"], article["description"], article["slug"], *article["tags"]]
+    return " ".join(fields).lower()
+
+
+def search(articles: list[Article], query: str, *, tag: str | None = None, limit: int = 10) -> list[Article]:
+    """Return newest-first articles whose text contains every term of `query`.
+
+    Terms are ANDed so that adding a word narrows the result, and `tag` further
+    restricts to one of the site's own tags. Both comparisons are case-insensitive.
+    """
+    terms = query.lower().split()
+    wanted = tag.lower() if tag else None
+    found = [
+        article
+        for article in articles
+        if all(term in _haystack(article) for term in terms)
+        and (wanted is None or wanted in {t.lower() for t in article["tags"]})
+    ]
+    return latest(found, limit=limit)
+
+
+def candidates(articles: list[Article], wanted: str) -> list[str]:
+    """Return the slugs `wanted` could mean: itself when exact, else every slug containing it."""
+    slugs = [article["slug"] for article in articles]
+    if wanted in slugs:
+        return [wanted]
+    return [slug for slug in slugs if wanted in slug]
+
+
+def by_slug(articles: list[Article], slug: str) -> Article | None:
+    """Return the article index entry for `slug`, if the profile lists it."""
+    return next((article for article in articles if article["slug"] == slug), None)

fmind-0.1.0/src/fmind/cli.py

@@ -0,0 +1,192 @@
+"""Command surface, mirroring the sections of www.fmind.dev."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Annotated, Any
+
+import typer
+from rich.console import RenderableType
+
+from fmind import __version__, articles, render
+from fmind.api import FmindError, load_article, load_profile
+
+app = typer.Typer(
+    name="fmind",
+    help="Read Médéric Hurier's (Fmind) portfolio from the terminal. Every command renders the live "
+    "profile published at https://www.fmind.dev/api/profile.",
+    add_completion=False,
+    no_args_is_help=True,
+    rich_markup_mode=None,
+)
+
+_STATE: dict[str, Any] = {"refresh": False, "json": False, "color": True}
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"fmind {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    refresh: Annotated[bool, typer.Option("--refresh", help="Ignore the cached copy and fetch it again.")] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Print the raw section as JSON instead of prose.")] = False,
+    color: Annotated[bool, typer.Option("--color/--no-color", help="Force or suppress ANSI colour.")] = True,
+    _v: Annotated[bool, typer.Option("--version", callback=_version, is_eager=True, help="Show the version.")] = False,
+) -> None:
+    """Store the global options for the section commands."""
+    _STATE.update(refresh=refresh, json=as_json, color=color)
+
+
+def _fail(message: str) -> typer.Exit:
+    """Report a clear one-line error on stderr and end the command."""
+    typer.secho(f"fmind: {message}", fg="red", err=True)
+    return typer.Exit(code=1)
+
+
+def _doc() -> dict[str, Any]:
+    """Load the profile, reporting a clear error instead of a traceback."""
+    try:
+        return load_profile(refresh=bool(_STATE["refresh"]))
+    except FmindError as error:
+        raise _fail(str(error)) from error
+
+
+def _emit(body: RenderableType, payload: Any, *, banner: dict[str, Any] | None = None) -> None:
+    """Print either the rendered section or its raw JSON."""
+    if _STATE["json"]:
+        json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+        return
+    out = render.console(color=bool(_STATE["color"]))
+    if banner is not None:
+        out.print(render.banner(banner))
+        out.print()
+    out.print(body)
+
+
+@app.command()
+def whoami() -> None:
+    """Name, current mission, contact and availability."""
+    doc = _doc()
+    _emit(render.whoami(doc), {"metadata": doc["metadata"], "services": doc["services"]}, banner=doc)
+
+
+@app.command()
+def about() -> None:
+    """The biography, as published on the site."""
+    doc = _doc()
+    _emit(render.about(doc), doc["biography"])
+
+
+@app.command()
+def skills() -> None:
+    """Core expertise, laid out like a usage screen."""
+    doc = _doc()
+    _emit(render.skills(doc), doc["expertise"])
+
+
+@app.command()
+def work() -> None:
+    """Engagements, current one first."""
+    doc = _doc()
+    _emit(render.work(doc), doc["experience"])
+
+
+@app.command()
+def community() -> None:
+    """Ambassador and advisory roles."""
+    doc = _doc()
+    _emit(render.community(doc), doc["leadership"])
+
+
+@app.command()
+def cert(
+    verify: Annotated[bool, typer.Option("--verify", help="List only credentials that are still active.")] = False,
+) -> None:
+    """Certifications, the PhD, and specializations."""
+    doc = _doc()
+    payload = [c for c in doc["certifications"] if c["active"]] if verify else doc["certifications"]
+    _emit(render.cert(doc, verify=verify), payload)
+
+
+@app.command()
+def papers() -> None:
+    """The doctorate and the peer-reviewed publications."""
+    doc = _doc()
+    _emit(render.papers(doc), {"thesis": doc["thesis"], "papers": doc["papers"]})
+
+
+@app.command()
+def project(
+    top: Annotated[int, typer.Option("--top", min=1, max=50, help="How many projects to show.")] = 6,
+) -> None:
+    """Open-source repositories and video series."""
+    doc = _doc()
+    _emit(render.project(doc, top=top), (doc["open_source"] + doc["youtube_series"])[:top])
+
+
+@app.command()
+def sites() -> None:
+    """Interactive tools published alongside the writing."""
+    doc = _doc()
+    _emit(render.sites(doc), doc["site_pages"])
+
+
+@app.command()
+def article(
+    limit: Annotated[int, typer.Option("--limit", min=1, max=200, help="How many articles to show.")] = 6,
+) -> None:
+    """The most recent writing."""
+    doc = _doc()
+    posts = articles.latest(doc["articles"], limit=limit)
+    footer = f"{len(doc['articles'])} published · {doc['metadata']['site_url']}/articles/"
+    _emit(render.articles(posts, footer=footer), posts)
+
+
+@app.command()
+def search(
+    query: Annotated[str, typer.Argument(help="Terms to match against titles, summaries, tags and slugs.")],
+    tag: Annotated[str | None, typer.Option("--tag", help="Restrict to one of the site's tags, such as Agent.")] = None,
+    limit: Annotated[int, typer.Option("--limit", min=1, max=200, help="How many matches to show.")] = 10,
+) -> None:
+    """Find articles by term, newest match first."""
+    doc = _doc()
+    found = articles.search(doc["articles"], query, tag=tag, limit=limit)
+    footer = f"{len(found)} shown · {len(doc['articles'])} published · fmind read <slug> opens one"
+    _emit(render.articles(found, footer=footer), found)
+
+
+@app.command()
+def read(
+    slug: Annotated[str, typer.Argument(help="Article slug, or enough of it to be unambiguous.")],
+    raw: Annotated[bool, typer.Option("--raw", help="Print the Markdown source instead of rendering it.")] = False,
+) -> None:
+    """Read one article in the terminal, from its published Markdown."""
+    doc = _doc()
+    matches = articles.candidates(doc["articles"], slug.strip().lower())
+    if not matches:
+        raise _fail(f"no article matches {slug!r} — try: fmind search {slug}")
+    if len(matches) > 1:
+        listed = "\n  ".join(matches[:10])
+        raise _fail(f"{slug!r} matches {len(matches)} articles:\n  {listed}")
+    resolved = matches[0]
+    try:
+        markdown = load_article(resolved, refresh=bool(_STATE["refresh"]))
+    except FmindError as error:
+        raise _fail(str(error)) from error
+    post = articles.by_slug(doc["articles"], resolved)
+    if raw and not _STATE["json"]:
+        sys.stdout.write(markdown)
+        return
+    _emit(render.article_body(markdown), {"slug": resolved, "markdown": markdown, **(post or {})})
+
+
+@app.command()
+def hire() -> None:
+    """What can be booked right now."""
+    doc = _doc()
+    _emit(render.hire(doc), doc["services"])

fmind-0.1.0/src/fmind/render.py

@@ -0,0 +1,272 @@
+"""Render sections of the portfolio document as terminal output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console, Group, RenderableType
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+
+ACCENT = "bold #00ff41"
+HI = "bold #ccffd9"
+DIM = "#57a86e"
+FLAG = "#7dffab"
+ERR = "#ff7a5c"
+
+WORDMARK = (
+    "█▀▀▀  █▄ ▄█  ▀█▀  █▄  █  █▀▀▄ ",
+    "█▄▄   █ ▀ █   █   █ █ █  █   █",
+    "█     █   █   █   █  ██  █   █",
+    "█     █   █  ▄█▄  █   █  █▄▄▀ ",
+)
+
+SKILL_FLAGS = {
+    "Agentic Orchestration": "--agents",
+    "Production MLOps": "--mlops",
+    "Security-First AI": "--security",
+    "Technical Strategy": "--strategy",
+    "Data Science & ML": "--data",
+    "Python Development": "--python",
+}
+
+
+def console(*, color: bool = True) -> Console:
+    """Build the output console; `color=False` yields plain text for pipes."""
+    return Console(no_color=not color, highlight=False, soft_wrap=False)
+
+
+def _rows(pairs: list[tuple[str, RenderableType]], key_width: int = 11) -> Table:
+    """Lay out aligned key/value rows without visible borders."""
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style=ACCENT, width=key_width, no_wrap=True)
+    table.add_column(overflow="fold")
+    for key, value in pairs:
+        table.add_row(key, value)
+    return table
+
+
+def banner(doc: dict[str, Any]) -> RenderableType:
+    """The wordmark beside the name, role and headline."""
+    meta = doc["metadata"]
+    mark = Text("\n".join(WORDMARK), style=ACCENT)
+    identity = Group(
+        Text(meta["name"], style=HI),
+        Text(meta["job_title"], style="#00ff41"),
+        Text(meta["headline_primary"], style=DIM),
+    )
+    side = Table.grid(padding=(0, 3))
+    side.add_column(no_wrap=True)
+    side.add_column(overflow="fold")
+    side.add_row(mark, identity)
+    return side
+
+
+def whoami(doc: dict[str, Any]) -> RenderableType:
+    """Identity, current mission, contact and availability."""
+    meta = doc["metadata"]
+    experience = doc.get("experience") or []
+    mission = Text("—", style=DIM)
+    if experience:
+        current = experience[0]
+        mission = Text(f"{current['company']} — {current['title']}", style="#74e492")
+    services = doc.get("services") or []
+    status = Text()
+    for index, service in enumerate(services):
+        open_now = service.get("badge_type") != "error"
+        if index:
+            status.append("\n")
+        status.append("● ", style="#00ff41" if open_now else ERR)
+        status.append(service["title"], style=HI)
+        status.append(f" — {service['badge']}", style=DIM)
+    return _rows(
+        [
+            ("Name", Text(f"{meta['name']} ({meta['alternate_name']})", style=HI)),
+            ("Role", Text(meta["job_title"], style="#74e492")),
+            ("Mission", mission),
+            ("Degree", Text(doc["thesis"]["institution_details"], style="#74e492")),
+            ("Contact", Text(meta["email"], style=FLAG)),
+            ("Website", Text(meta["site_url"], style=FLAG)),
+            ("Status", status),
+        ]
+    )
+
+
+def about(doc: dict[str, Any]) -> RenderableType:
+    """The biography paragraphs."""
+    return Group(*(Padding(Text(p, style="#74e492"), (0, 0, 1, 0)) for p in doc["biography"]))
+
+
+def skills(doc: dict[str, Any]) -> RenderableType:
+    """Expertise laid out like a usage screen, matching www.fmind.dev."""
+    flags = [SKILL_FLAGS.get(card["title"], "--" + card["title"].split()[0].lower()) for card in doc["expertise"]]
+    synopsis = Text("fmind", style=ACCENT)
+    synopsis.append(" skills ", style=HI)
+    synopsis.append(" ".join(f"[{flag}]" for flag in flags), style=FLAG)
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style=FLAG, width=12, no_wrap=True)
+    table.add_column(overflow="fold")
+    for card, flag in zip(doc["expertise"], flags, strict=True):
+        body = Text(card["title"], style=HI)
+        body.append(f" — {card['description']}", style=DIM)
+        table.add_row(flag, body)
+    return Group(
+        Text("USAGE", style=DIM),
+        Padding(synopsis, (0, 0, 1, 2)),
+        Text("OPTIONS", style=DIM),
+        Padding(table, (0, 0, 0, 2)),
+    )
+
+
+def work(doc: dict[str, Any]) -> RenderableType:
+    """Engagements, current one first."""
+    blocks: list[RenderableType] = []
+    for index, job in enumerate(doc["experience"]):
+        head = Text(job["company"].upper(), style=ACCENT)
+        if index == 0:
+            head.append(" · current", style=DIM)
+        body = Group(
+            head,
+            Text(job["title"], style=HI),
+            Text(job["description"], style=DIM),
+            Text("  ".join(job["tags"]), style=FLAG),
+        )
+        blocks.append(Padding(body, (0, 0, 1, 0)))
+    return Group(*blocks)
+
+
+def community(doc: dict[str, Any]) -> RenderableType:
+    """Ambassador and advisory roles."""
+    return _rows(
+        [
+            (r["organization"][:11], Group(Text(r["role"], style=HI), Text(r["description"], style=DIM)))
+            for r in doc["leadership"]
+        ],
+        key_width=13,
+    )
+
+
+def cert(doc: dict[str, Any], *, verify: bool = False) -> RenderableType:
+    """Credentials, plus specializations unless `verify` narrows to active ones."""
+    table = Table.grid(padding=(0, 2))
+    table.add_column(width=8, no_wrap=True)
+    table.add_column(overflow="fold")
+    for badge in doc["certifications"]:
+        active = bool(badge["active"])
+        if verify and not active:
+            continue
+        state = Text("active" if active else "expired", style="#00ff41" if active else DIM)
+        body = Text(badge["title"], style=HI if active else "#74e492")
+        body.append(f" — {badge['issuer']}", style=DIM)
+        table.add_row(state, body)
+    thesis = Text(doc["thesis"]["title"], style=HI)
+    thesis.append(f" — {doc['thesis']['institution_details']}", style=DIM)
+    parts: list[RenderableType] = [table, Padding(Group(Text("PhD", style=ACCENT), thesis), (1, 0, 0, 0))]
+    if not verify:
+        specs = Text("\n".join(f"  {s['title']} — {s['issuer_details']}" for s in doc["specializations"]), style=DIM)
+        parts.append(Padding(Group(Text("SPECIALIZATIONS", style=DIM), specs), (1, 0, 0, 0)))
+    return Group(*parts)
+
+
+def project(doc: dict[str, Any], *, top: int = 6) -> RenderableType:
+    """Open-source repositories and video series."""
+    items = [(p["title"], p["description"], p["href"]) for p in doc["open_source"]]
+    items += [(v["title"], v["description"], v["url"]) for v in doc["youtube_series"]]
+    blocks = [
+        Padding(Group(Text(title, style=HI), Text(description, style=DIM), Text(url, style=FLAG)), (0, 0, 1, 0))
+        for title, description, url in items[: max(top, 0)]
+    ]
+    return Group(*blocks)
+
+
+def articles(posts: list[dict[str, Any]], *, footer: str = "") -> RenderableType:
+    """A list of articles, one block each, with `fmind read` slugs kept visible."""
+    blocks: list[RenderableType] = []
+    for post in posts:
+        head = Text(post["date"][:10], style=ACCENT)
+        head.append(f"  {post['reading_minutes']} min", style=DIM)
+        head.append(f"  {'  '.join(post['tags'])}", style=FLAG)
+        body = Text("fmind read ", style=DIM)
+        body.append(post["slug"], style=FLAG)
+        blocks.append(Padding(Group(head, Text(post["title"], style=HI), body), (0, 0, 1, 0)))
+    if not blocks:
+        return Text("no article matches", style=DIM)
+    return Group(*blocks, Text(footer, style=DIM)) if footer else Group(*blocks)
+
+
+def article_body(markdown: str) -> RenderableType:
+    """One article, rendered from its published Markdown source.
+
+    The source already opens with the title, summary, date, reading time, tags and
+    canonical URL, so nothing is prepended here.
+    """
+    return Markdown(markdown, code_theme="ansi_dark", hyperlinks=False)
+
+
+def papers(doc: dict[str, Any]) -> RenderableType:
+    """The doctorate and the peer-reviewed record behind it."""
+    thesis = doc["thesis"]
+    head = Group(
+        Text("PhD", style=ACCENT),
+        Text(thesis["title"], style=HI),
+        Text(thesis["institution_details"], style="#74e492"),
+        Text(thesis["description"], style=DIM),
+        Text(thesis["url"], style=FLAG),
+    )
+    parts: list[RenderableType] = [Padding(head, (0, 0, 1, 0))]
+    for link in thesis.get("links") or []:
+        row = Text("  ", style=DIM)
+        row.append(link["label"], style="#74e492")
+        row.append(f"  {link['url']}", style=FLAG)
+        parts.append(row)
+    if thesis.get("links"):
+        parts.append(Text())
+    parts.append(Text("PUBLICATIONS", style=ACCENT))
+    for paper in doc["papers"]:
+        body = Group(
+            Text(paper["title"], style=HI),
+            Text(paper["venue"], style=DIM),
+            Text(paper["url"], style=FLAG),
+        )
+        parts.append(Padding(body, (1, 0, 0, 0)))
+    return Group(*parts)
+
+
+def sites(doc: dict[str, Any]) -> RenderableType:
+    """Interactive tools published alongside the writing."""
+    blocks = [
+        Padding(
+            Group(
+                Text(page["title"], style=HI),
+                Text(page["description"], style=DIM),
+                Text(f"for {page['audience']}", style="#74e492"),
+                Text(page["url"], style=FLAG),
+            ),
+            (0, 0, 1, 0),
+        )
+        for page in doc["site_pages"]
+    ]
+    return Group(*blocks) if blocks else Text("no interactive site published", style=DIM)
+
+
+def hire(doc: dict[str, Any]) -> RenderableType:
+    """What can be booked right now."""
+    blocks: list[RenderableType] = []
+    for service in doc["services"]:
+        open_now = service.get("badge_type") != "error"
+        state = Text("● ", style="#00ff41" if open_now else ERR)
+        state.append(service["badge"], style="#00ff41" if open_now else ERR)
+        blocks.append(
+            Padding(
+                Group(
+                    Text(service["title"], style=HI),
+                    Text(service["description"], style=DIM),
+                    state,
+                    Text(service["cta_url"], style=FLAG),
+                ),
+                (0, 0, 1, 0),
+            )
+        )
+    return Group(*blocks)