www

# www

<!-- mcp-name: io.github.fmind/portfolio -->

[Médéric Hurier (Fmind)](https://www.fmind.dev/), freelance AI Architect specializing in AI agents, MLOps, and security. The website is server-rendered Python: Litestar, strict Jinja, Tailwind CSS v4, DaisyUI v5, and Granian. Small page-specific JavaScript controllers enhance native navigation and forms. There is no client framework, application database, runtime CDN, cookie, or client-side analytics.

## Development

Requires [mise](https://mise.jdx.dev/), Docker Engine with Buildx, and network access for initial tool/browser installation and image/scanner downloads. Python 3.14.7 and the remaining toolchain are pinned in `mise.toml` and `mise.lock`; `.mise/locks/` records the browser tools' transitive npm dependencies and must be committed with lock updates.

```bash
mise install
mise run install
mise run watch
```

Open `http://localhost:8080`; use `PORT=8081 mise run watch` for another port. `.env.example` lists runtime variables; `.env` files are not loaded automatically. The default environment is `development`; production sets `ENVIRONMENT=production`. Reload watches `src/`, `content/`, and `static/`; restart after environment/configuration changes.

`src/www/app.py` constructs the immutable startup snapshot and routes. `src/www/__main__.py` starts Granian. Templates are wheel package data; the image copies the separate `content/` and `static/` trees beside the locked environment. [AGENTS.md](AGENTS.md) maps module ownership and invariants.

## Content and design

`src/www/data.py` supplies portfolio facts, service availability, HTML, JSON/JSON-LD, vCard, and LLM text. Preserve the owner's voice and factual claims across these surfaces.

The light-only [fmind/theme](https://github.com/fmind/theme) palette uses white, light gray, charcoal, and blue `#174EA6`. `assets/css/input.css` owns interface colors; `src/www/highlighting.py` owns syntax colors. Tests enforce the palette with explicit company-brand exceptions. Tailwind scans `src/www/templates/**/*.html`.

Fonts are self-hosted Google Sans and Google Sans Code subsets. The font generator pins upstream releases, removes reserved logo ligatures, and preserves timestamps. Public branding masters are `/logo.png` and `/banner.png`. Keep private portrait originals outside `static/`; `build:portrait` exports `/portrait.jpg` with orientation/ICC preserved and personal metadata removed.

Share `/connect` at events; it offers LinkedIn, a vCard, and the full website. `/scan` is a noindex QR utility. The UTF-8 vCard 3.0 derives public professional details and a sanitized portrait from portfolio data, without a phone number, street address, birthday, or precise coordinates.

Articles in `content/articles/` use strict TOML frontmatter. Their validated collection feeds every publication surface, excluding drafts in production. `build:images` generates responsive WebP derivatives and the SHA-256 provenance lock; `check:images` never writes. Figures fit the 1280px column; code highlighting is server-side. Articles with at least two main sections show an H2-only 256px navigation rail at viewport widths of 1920px and above, with two-line labels and full titles on hover; links work without JavaScript, which adds current-section highlighting. Follow the [article skill](.agents/skills/article/SKILL.md).

Decision tools use typed Python formulas, native GET forms, dated sources, and explicit planning limits. Register them in `data.py:SITE_PAGES`; follow the [site skill](.agents/skills/site/SKILL.md). See [AGENTS.md](AGENTS.md) for module ownership and invariants.

## Tasks

`mise.toml` is the canonical contract used by hooks and CI; `mise tasks` lists all tasks and aliases.

| Command                                                    | Purpose                                                                                                     |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `mise run all`                                             | Format, checks, build, pytest, OCI build/scan/smoke, Chromium install, browser journeys                     |
| `mise run check`                                           | Metadata/locks, Ruff, ty, dprint, secrets, dependencies, Docker/IaC/workflow scans, image provenance, typos |
| `mise run test`                                            | Offline pytest with branch coverage ≥85% and warnings as errors                                             |
| `mise run check:tofu`                                      | Backend-free provider validation, tflint, and mocked infrastructure plan tests                              |
| `mise run check:links`                                     | Network-dependent external-link audit; scheduled separately from merge gates                                |
| `mise run test:browser`                                    | Desktop/mobile Chromium journeys                                                                            |
| `mise run test:browser:cross`                              | Focused Firefox/WebKit journeys                                                                             |
| `mise run test:lighthouse:local`                           | Temporary local server and strict ten-audit portfolio matrix                                                |
| `mise run build`                                           | Production CSS, wheel, and source distribution                                                              |
| `mise run check:image`                                     | Build and scan `tmp/www-image.tar`                                                                          |
| `mise run test:image [digest-ref]`                         | Smoke-test the existing archive or exact remote digest                                                      |
| `mise run check:image:deployed`                            | Resolve and scan every image receiving Cloud Run traffic                                                    |
| `mise run build:branding` / `build:fonts` / `build:images` | Regenerate reviewed assets on demand                                                                        |
| `mise run build:portrait <private-master.jpg>`             | Export the sanitized public portrait                                                                        |
| `mise run test:candidate` / `test:deployed`                | CI release checks of the tagged candidate and promoted traffic; need `IMAGE_REF`, `GITHUB_SHA`, and gcloud  |
| `mise run deploy <digest-ref> <commit-sha>`                | Manual image rollout/rollback with commit label and full traffic; production-mutating                       |

`all` runs sequentially and reuses build outputs and its image archive. It requires Docker/Buildx but no cloud credentials. Asset generators, `clean`, watchers, live scans, and deployment run only on demand; `clean` deletes generated output.

Lighthouse stays separate: install Chromium, then use `mise run test:lighthouse -- --base-url <origin> --mode portfolio` for ten desktop/mobile audits of the portfolio, contact, privacy, and archive indexes. `smoke` runs four audits; default `full` covers the sitemap plus 48 stress audits. Run performance audits without concurrent builds or font generation; keep exact per-page scores.

Cross-browser checks require `install:browser:cross` and [Playwright system libraries](https://playwright.dev/docs/browsers#system-dependencies), or a matching official browser container via `PW_TEST_CONNECT_WS_ENDPOINT`. The [weekly/manual quality workflow](.github/workflows/quality.yml) provisions ephemeral runners and retains evidence for 14 days. Run browser suites sequentially because they share local port 8096. Set `BROWSER_BASE_URL=https://www.fmind.dev` for production journeys; local servers otherwise start and stop automatically.

Dispatch that workflow with `gh workflow run quality.yml -f target=production` after verifying the deployed commit to run Chromium, Firefox, WebKit, and the same strict Lighthouse matrix against the public site on clean runners. The default `local` target qualifies the checkout; production mode does not deploy or change the service. Use runner evidence when other workstation workloads distort performance measurements, preserving failed reports and score thresholds.

## Deployment

Cloud Run serves <https://www.fmind.dev/> in project `www-fmind-dev`, region `europe-west1`. [infra/](infra/) owns service settings, registry, keyless identities, alerts, and analytics. Keep **minimum instances at 0 at both service and revision levels**, maximum 5, and request-based CPU. The qualified runtime uses 1 CPU, 512 MiB, concurrency 8, a 30-second request timeout, and twelve startup attempts five seconds apart. Startup builds article Markdown once for HTTP, LLM text, and MCP. Maximum instances limits scaling; it is not a hard billing cap.

A `main` push runs the full gate, builds a non-root image with SBOM/provenance, pushes it, and scans and smoke-tests its immutable digest. It then creates a no-traffic revision under the `candidate` tag; `test:candidate` requires that revision to match `IMAGE_REF`/`GITHUB_SHA` and to serve health, profile, and the MCP server card on its tagged `run.app` URL. Only then does CI route 100% of traffic to that exact revision; a failed candidate leaves traffic on the previous revision. `test:deployed` finally verifies that the ready revision receiving 100% of traffic matches `IMAGE_REF` and `GITHUB_SHA`, preserves scale-to-zero checks, and probes public health/profile/MCP discovery. Error-log review remains an independent release check because the deployer has no log-reading role. Actions are SHA-pinned and Dependabot maintains ecosystem updates.

Workload Identity Federation accepts only `main` tokens from the numeric reposi