DEV Community: Fernando Paladini

Stop Guessing localhost Ports with portmap and TypeScript

Fernando Paladini — Sat, 24 Oct 2026 12:31:02 +0000

AI coding agents are very good at remembering common conventions. That is also why they can be very confident and completely wrong about localhost:3000.

One project may expose a Vite frontend on port 5173. Another may run an API on 8080. A Docker mapping can make the host port different from the container port, while an .env.local file may still point to a service that is not running today. The resulting error often looks like CORS, authentication, or a broken API client when the real problem is a stale URL.

portmap is a small MIT-licensed TypeScript CLI and read-only MCP server for this local-development problem. It combines declared configuration, optional OS listener data, and environment references into a .portmap.json report with findings such as PRT-04 for an environment URL that points at a port with no listener.

This tutorial uses the current repository configuration and the checked-in mismatch fixture. You will build portmap from source, run a deterministic static scan, inspect the generated findings, and understand where the tool deliberately stops.

TL;DR

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci
npm run build
node dist/cli.js declare fixtures/mismatch --json

The output identifies a declared Vite port and two unresolved localhost environment URLs. That gives an agent or a developer concrete evidence before changing application code.

Prerequisites

You need:

Node.js 20 or newer. The repository declares engines.node as >=20.
npm and Git.
A Windows, macOS, or Linux development machine for the documented runtime listener support. The static declare command does not need a running service.

The repository is public, non-archived, non-forked, and uses the MIT license. At the time of writing, the repository reports version 0.1.0 in package.json and does not provide a GitHub release, so the reproducible path below pins the source checkout by its current default branch rather than claiming a released package.

Build portmap from the repository

Clone the project and install the lockfile exactly:

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci
npm run build

The build runs TypeScript with the repository's tsconfig.json and produces the dist directory. The CLI entry point is dist/cli.js; the package metadata also exposes a portmap binary when the project is installed as a package.

The current README documents npm ci, npm run build, and node dist/cli.js as the source-based installation path. It also documents npx portmap as a future npm option, so do not use the latter as if a published npm package were already verified.

Run a static topology check

The safest first check is declare. It reads project files without requiring the application's processes to be running:

node dist/cli.js declare fixtures/mismatch --json

The fixture is intentionally broken. Its configuration declares a Vite server on port 5173, while .env.local contains references to http://localhost:3000 and http://localhost:8080. Because no matching service is declared for those references, the report contains unresolved environment edges.

The important part of the JSON is the relationship between the declared service, references, and findings:

{
  "services": [
    {
      "id": "vite",
      "declared": {
        "port": 5173,
        "sources": ["vite.config.ts:server.port"]
      },
      "status": "down"
    }
  ],
  "findings": [
    {
      "id": "PRT-01",
      "severity": "error"
    },
    {
      "id": "PRT-04",
      "severity": "error",
      "file": ".env.local:1"
    }
  ]
}

The complete report includes the second PRT-04 for the port 8080 reference. The fixture has no listener data because this static command does not inspect the operating system.

Use the result in a real project

Run declare against your application first:

node /path/to/portmap/dist/cli.js declare /path/to/your-app --json

If the report is useful as persistent agent context, write it to the project root:

node /path/to/portmap/dist/cli.js declare /path/to/your-app --write

This creates .portmap.json. The repository's schema documentation describes it as the artifact agents can read instead of guessing a URL. Whether you commit it is a project decision: committing it can make a known local topology available to future sessions, while ignoring it avoids storing machine-specific runtime data.

When processes are running, the full command adds an OS listener scan:

node /path/to/portmap/dist/cli.js scan /path/to/your-app --json

The full scan can report declared ports that are not listening, listeners without declared configuration, mismatched Docker host and container ports, and environment references that do not resolve. The README also documents workspace for projects in sibling folders and listen for inspecting listeners directly.

Add a read-only MCP server

portmap includes a read-only MCP stdio server. After building, the command is:

node /path/to/portmap/dist/cli.js mcp

For Cursor or Claude Code, the documented configuration points the MCP command at the built CLI:

{
  "mcpServers": {
    "portmap": {
      "command": "node",
      "args": ["/path/to/portmap/dist/cli.js", "mcp"]
    }
  }
}

The exposed tools are intentionally narrow: retrieve a full report, get a smaller service graph, resolve a URL, or filter findings. The server does not start or stop services, modify application files, or infer ports with an LLM.

Why the reconciliation is useful

The core design separates three kinds of evidence:

Declared configuration tells you what the project says should run. portmap looks at package scripts, Vite configuration, environment URLs, and common Docker Compose port mappings.
Runtime discovery tells you what the operating system says is listening. This is optional because a static check is still valuable before startup.
Reconciliation connects declarations, listeners, and environment references into services, edges, and findings.

That separation makes a failure actionable. PRT-04 means an environment URL points at a port with no listener, while PRT-02 warns about a listener without a corresponding declaration. Those are different repair paths, even though both can surface as a browser network error.

CI verification

The CLI can turn findings into a non-zero exit status. For example, this command fails when at least one error remains:

node dist/cli.js scan . --min-findings 1 --min-severity error --json

Use this as a local-development guard, not as production monitoring. The project is designed for local service topology and explicitly does not provide uptime or production health checks.

Failure modes and security boundaries

There are several important boundaries:

Runtime-only ports that are hardcoded in JavaScript without a discoverable configuration can produce a PRT-02 warning or remain undiscovered.
WSL and Docker networking can make a container listener invisible from the host perspective.
The current YAML Compose support handles common ports: patterns, not every Compose feature.
PID-to-repository attribution is heuristic. Low-confidence matches are flagged rather than presented as certain.
The MCP server is read-only, but a local MCP client still decides which project path to pass to it. Review client configuration and avoid exposing sensitive directories unnecessarily.

The tool reads local configuration and socket information. It is not a secret manager, a process supervisor, or a security guarantee. Keep .env values out of reports and repositories when they contain credentials; the useful signal is the referenced host and port, not the secret itself.

Reproducible verification

From the clean checkout, verify the source path and fixture again:

npm ci
npm run build
node dist/cli.js declare fixtures/mismatch --json > mismatch-report.json

Confirm that the JSON parses and contains PRT-01 plus the unresolved PRT-04 findings. For your own project, change one environment URL to the actual declared port, rerun the command, and compare the findings. That gives you a small, reproducible experiment instead of relying on whether an agent happens to guess correctly.

The repository also includes npm test, demo:mismatch, and demo:workspace scripts. In a clean Windows checkout, the build and static fixture declaration are useful smoke checks; if a runtime listener check behaves differently on your platform, treat that as an environment-specific result and inspect the generated report rather than assuming the listener model is universal.

FAQ

Does portmap replace Docker or a process manager?

No. It reports topology. It does not start, stop, or restart services.

Does it require an AI model?

No. The repository describes the scanner and MCP server as deterministic and zero-LLM. The MCP interface is for letting an agent consume evidence, not for outsourcing discovery to a model.

Can I install it from npm today?

The README lists npm installation as a future option. The verified current path is cloning the repository, running npm ci, and building locally.

Should `.portmap.json` be committed?

Only if the values are stable and safe to share. A committed static report can help future agents, but machine-specific listeners and environment details may be inappropriate for a repository.

Takeaway

The practical lesson is simple: make local topology an input to debugging. Build portmap from the documented source path, run declare before starting a long investigation, and let the report show which URLs are declared, which are actually reachable, and which assumptions are unsupported.

If you try this in a monorepo, which mismatch would be most valuable to catch first: stale environment URLs, Docker port remapping, or cross-workspace references?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. Repository behavior, commands, metadata, limitations, and verification claims were checked against the current public source and the clean checkout described above.

Build a Mobile Guitar Tuner with React, Express, and PostgreSQL

Fernando Paladini — Fri, 23 Oct 2026 12:35:12 +0000

If you want a guitar tuner that is easy to open on a phone or smartwatch, a small local web app can be more practical than a native installation. The hard part is not drawing six buttons. It is keeping the local setup reproducible while making the browser experience usable on a small screen.

This tutorial walks through the current main branch of Guitar Tune Trainer, an MIT-licensed open-source project owned by Fernando Paladini. You will install the project, start its PostgreSQL service, run the checks and production build, and understand what the repository currently does and does not provide.

TL;DR

The project is a React and Vite front end served by an Express application. Its documented local path is:

Install Node.js 18+, npm, and PostgreSQL support.
Clone the repository and run npm install.
Start PostgreSQL with the included Docker Compose file, or use another local database.
Copy .env.sample to .env and set a local SESSION_SECRET.
Run npm run db:push, then npm run dev.

The current repository also passes npm ci, npm run check, and npm run build on commit 26cfe55744aad30f2d30f03cdf70244bc0a91809.

Prerequisites

You need:

Node.js 18 or newer
npm
Docker Desktop with Compose, or a reachable PostgreSQL database
A modern browser if you want to use the mobile-oriented interface

The repository has no GitHub release or stable tag at the time of writing. Treat the commands below as instructions for the current main branch, not as a promise that a future release will have identical dependencies.

Start PostgreSQL locally

The repository includes a small docker-compose.yml that starts PostgreSQL 16 with a named volume:

docker compose up -d

The checked-in Compose configuration uses these local development values:

POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: guitar_tune_trainer

It publishes PostgreSQL on port 5432. These are development credentials from the repository configuration. Do not reuse them on a shared or internet-exposed database.

If port 5432 is already occupied, either stop the conflicting service or change the host-side port mapping. If you change the host port, update the connection string accordingly.

Install and configure the app

Clone the project and install the lockfile dependencies:

git clone https://github.com/paladini/guitar-tune-trainer.git
cd guitar-tune-trainer
npm ci

The current package.json identifies the package as version 1.0.0, uses ES modules, and declares the MIT license. Its scripts include dev, build, start, check, and db:push.

Create the local environment file from the checked-in example:

cp .env.sample .env

On Windows PowerShell, use this equivalent command:

Copy-Item .env.sample .env

The example contains:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/guitar_tune_trainer
SESSION_SECRET=your-session-secret
PORT=5000

Replace your-session-secret with a random value before using the app beyond a disposable local session. Keep .env out of version control. The repository's .gitignore is intended to support that local configuration pattern.

Apply the database schema and run the app

The repository's Drizzle configuration reads DATABASE_URL, and the documented schema currently defines a users table with a serial ID, unique username, and password field. Apply that schema with:

npm run db:push
npm run dev

The Express entry point defaults to port 5000, listens on 0.0.0.0, and serves the Vite development app after registering the server routes. Open http://localhost:5000 in a browser.

The HTML entry point is explicitly mobile-oriented. It sets a responsive viewport, describes the page as a smartwatch and mobile guitar tuner, links a web manifest, and includes Apple web-app metadata. The README describes the project as a PWA with offline support. Verify those capabilities in the browser you intend to use rather than assuming every browser exposes the same install prompt or audio behavior.

What the current code actually provides

The project is easiest to understand as two layers:

The client is a React application bundled with Vite and styled with Tailwind CSS and component primitives.
The server is an Express host with Drizzle-related database configuration and a memory-backed user storage implementation.

That distinction matters. The current server/routes.ts creates the HTTP server but does not register application API endpoints. The storage class keeps users in a process-local Map, while the shared schema describes PostgreSQL tables. The repository therefore demonstrates a runnable full-stack shell and a mobile tuner experience, but it is not yet a complete account-backed production service.

This is also why the first verification target should be the local page and build, not a claim that user data is persisted across restarts.

Reproducible verification

From a clean checkout, run the same checks used for this tutorial:

npm ci
npm run check
npm run build

npm ci installs the exact versions recorded in package-lock.json. npm run check runs TypeScript checking through tsc. npm run build runs the Vite client build and bundles the Express server with esbuild into dist.

On the current commit, all three commands completed successfully. The install also reported 35 audit findings in the dependency tree: 3 low, 11 moderate, 20 high, and 1 critical. That result is a reason to review and update dependencies before exposing the app publicly, not a reason to claim that the application is secure.

After the build, you can use the production-shaped command locally:

npm start

The application still requires the configured environment and database assumptions. Stop it with Ctrl+C when the smoke test is complete.

Failure modes and boundaries

PostgreSQL does not start

Check whether port 5432 is already in use and inspect the Compose logs:

docker compose ps
docker compose logs db

If you use a managed PostgreSQL provider instead, set DATABASE_URL to that provider's connection string and follow its TLS requirements.

The browser cannot access audio features

The repository presents reference-tone functionality as part of the tuner experience, but browser audio policies vary. Test on the target phone or watch, allow audio when prompted, and do not assume that a desktop result reproduces on a wearable browser.

Database changes appear not to persist

The schema and database configuration do not mean every feature is backed by PostgreSQL. The current route file has no registered application endpoints, and MemStorage stores users only in memory. Treat persistence as an unfinished boundary until the implementation changes and is verified.

Development credentials leak into deployment

The Compose file intentionally uses simple local credentials. Replace them, restrict network exposure, use a secret manager, and rotate any credential that may have been copied outside a disposable development environment.

FAQ

Can I run it without Docker?

Yes. The README lists local, Docker, or Neon PostgreSQL as options. Set DATABASE_URL to the database you control and run the same schema command.

Is there a stable release to pin?

No GitHub release or tag was present during this review. Pin a commit when reproducibility matters, and recheck the README and package metadata before upgrading.

Is this a production-ready authentication system?

No. The current repository contains a schema and in-memory storage skeleton, not a completed authentication flow. Do not put real credentials into it without implementing and reviewing authentication, password hashing, session handling, authorization, and database persistence.

Takeaway

Guitar Tune Trainer is a useful example of a small mobile-first full-stack web project: the command surface is compact, the browser entry point is designed for small screens, and the build is easy to verify locally. Its honest value today is the runnable interface and development scaffold. Its server-side persistence and security model still need deliberate engineering before deployment.

What would you build next: browser microphone pitch detection, a completed persisted account flow, or a smaller offline-only tuner with no server at all?

AI assistance disclosure

AI assistance was used to organize this tutorial and review the documented commands against the public repository. The repository behavior, configuration values, limitations, and validation results were checked against the cited primary sources and a clean local checkout.

Turn Spec Drift into a Pull Request Check with SpecGov

Fernando Paladini — Thu, 22 Oct 2026 12:34:30 +0000

TL;DR

Spec-driven development is useful only while the code and its governing artifacts stay aligned. SpecGov is a local, MIT-licensed CLI and GitHub Action that maps implementation paths to requirements, ADRs, docs, or specs, then reports when a code change bypasses them.

This tutorial uses the stable v0.1.0 release to build a small manifest, run a local scan, simulate a pull request check, and add the same check to GitHub Actions. The workflow is advisory first, so a team can learn where its mappings are incomplete before making them blocking.

What you will build

By the end, a repository will have a .specgov.yml manifest that says which artifacts govern src/auth/**. SpecGov can then report a warning when a pull request changes src/auth/session.ts without changing a related specification or design document.

SpecGov does not replace a spec-authoring method. It works with existing Markdown contracts, ADRs, .specs folders, Kiro specs, and Spec Kit plans. It reads local files and Git metadata. The project documentation describes it as framework agnostic, PR native, advisory first, and private by default.

Prerequisites

You need:

Node.js 20 or newer. The package declares node >=20.
A Git repository with a few documentation or specification files.
Git, if you want to run the pull request comparison locally.
A GitHub repository if you want to add the Action.

The stable release is specgov@0.1.0, published under the MIT license. The current repository also contains newer pre-release work, so pin the version when you need repeatable behavior.

Install the stable CLI

You can install the published CLI globally:

npm install -g specgov@0.1.0

Or use it without changing the global environment:

npx specgov@0.1.0 --help

The CLI exposes init, scan, check-pr, trace, and drift. The first four are enough for a useful pull request gate. The v0.1.0 README documents the complete command surface and exit codes.

Add a small manifest

Create .specgov.yml at the repository root. Start with one high-value mapping instead of trying to govern every path immediately:

version: 1
mode: advisory

artifacts:
  - path: "docs/**/*.md"
    kind: documentation
    owner: docs
  - path: "adr/**/*.md"
    kind: decision
    owner: architecture
  - path: ".specs/**/*.md"
    kind: specification
    owner: engineering

mappings:
  - code: "src/auth/**"
    specs:
      - "docs/auth/**"
      - "adr/auth/**"
      - ".specs/features/auth/**"
    description: Authentication behavior must stay aligned with its specs.

rules:
  require_spec_impact_for_code_changes: true
  require_lifecycle_status: false
  require_owner_for_active_specs: false
  stale_after_days: 180

ignore:
  - "node_modules/**"
  - "dist/**"
  - ".git/**"

The artifacts entries tell SpecGov what belongs to the repository's governance layer. A mappings entry connects implementation paths to the artifacts that must move with them. The mapping is explicit: an unrelated changed document does not satisfy the rule by accident.

Keep mode: advisory while the manifest is new. Advisory mode reports warnings but returns success for those warnings. Strict mode returns exit code 1 when governance findings should block a pull request.

Run the local checks

First scan the repository and emit JSON for a script or CI job:

specgov scan --format json

Then simulate a pull request that changes an authentication file:

specgov check-pr --format json --changed-file src/auth/session.ts

With the manifest above and no related spec change, the result should contain a SPEC_IMPACT_MISSING warning. That warning is useful evidence, not a failure in advisory mode. It tells the author which code path changed and which spec roots should be considered.

For a human-readable report, omit --format json:

specgov check-pr --changed-file src/auth/session.ts

You can also create a trace index for automation:

specgov trace --out .specgov.trace.json

The exact report depends on your repository. The important verification is reproducible: run the same command against the same checkout and inspect the finding code, related files, status, and exit code.

Add the GitHub Action

Once the local mapping makes sense, add a workflow such as .github/workflows/specgov.yml:

name: SpecGov

on:
  pull_request:

jobs:
  specgov:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: paladini/specgov@v0.1.0
        with:
          mode: advisory
          base-ref: ${{ github.event.pull_request.base.sha }}
          head-ref: ${{ github.event.pull_request.head.sha }}

The repository's stable README uses the same action contract and recommends pinning the Action to a version tag for repeatable CI behavior. The checkout needs full history because the check compares the pull request's base and head references.

When the mapping has earned trust, change mode to strict for the paths you are ready to enforce. Treat that as a policy decision: a strict rule can block a pull request, so the mapped artifact roots must be maintained with the same care as source code.

Why this works

The useful abstraction is a small graph:

Artifact globs identify the documents that can govern behavior.
Code-to-spec mappings connect implementation paths to those artifacts.
Git changes provide the pull request scope.
SpecGov compares the scope with the mappings and emits Markdown or JSON evidence.

This is more precise than checking whether a repository contains a file named SPEC.md. It also avoids asking an agent or model to guess which document matters. The manifest makes the relationship explicit and reviewable.

Failure modes and limitations

An empty glob or a typo in a path can make a mapping look complete while matching nothing. Run scan and review its artifact list before enabling strict mode.

SpecGov does not prove that a requirement is correct, that an implementation satisfies the requirement semantically, or that a declared producer really authored an artifact. It reports structural relationships and policy findings. A passing scan is not a correctness guarantee.

The stable release is marked pre-release in its README, and the CLI, report shape, and Action inputs may change before a first mature release. Pin 0.1.0 in tutorials and workflows, then review changes before upgrading.

The security boundary is intentionally narrow. Version 0.1 runs locally or in the GitHub runner, does not require an API key, does not call a model, and does not upload repository contents. That does not make the surrounding runner trusted automatically. Review third-party Actions, protect workflow changes, and avoid exposing private reports in public logs.

FAQ

Does SpecGov require GitHub?

No. The CLI can run locally in any Git repository. GitHub Actions is an integration point for pull request review.

Does it support only one specification framework?

No. The stable release supports custom folders and mappings, including docs, ADRs, .specs, Kiro-style specs, and Spec Kit-style plans.

Should every repository start in strict mode?

No. Start advisory, fix empty or overly broad mappings, observe real findings, and make only trusted paths strict.

Does a warning mean the code is unsafe?

No. It means the configured governance relationship is incomplete for the changed path. A reviewer still needs to decide whether the code, artifact, or mapping should change.

Takeaway

Spec drift becomes actionable when a repository can state which artifacts govern which code paths. SpecGov turns that statement into a deterministic local check and a pull request report. Start with one mapping, keep it advisory, verify the findings, and tighten enforcement only when the repository's own evidence supports it.

AI assistance disclosure: I used AI assistance to organize this tutorial and edit its prose. The project behavior, commands, configuration, version, license, limitations, and verification results were checked against the public repository, the stable v0.1.0 tag, package metadata, and local test/build commands.

What is the first code-to-artifact mapping in your repository that would benefit from an advisory check?

Learn Your Writing Style Locally with AuthorStyle and Python

Fernando Paladini — Wed, 21 Oct 2026 12:35:27 +0000

If you want an AI system to write in a style that feels like yours, the first problem is not a clever prompt. It is deciding what "your style" means and how to test whether a generated passage resembles it.

AuthorStyle takes a research-oriented approach to that problem. It is a Python command-line tool that learns recurring patterns from a local corpus, records evidence for its style profile, and evaluates generated candidates against held-out writing. The project is alpha software, so the useful outcome is an inspectable experiment, not a promise of a perfect voice clone.

TL;DR

Install AuthorStyle 0.2.1, create a profile, ingest a directory of Markdown or other supported documents, and analyze it locally. The minimal path produces corpus statistics and a Style Card with measurable observations such as sentence rhythm, paragraph rhythm, lexical diversity, and punctuation rates.

This tutorial uses the repository's English fixtures so the workflow is reproducible without supplying private writing. Replace that directory with your own corpus only after reviewing the privacy mode and data-handling boundaries.

Prerequisites

You need:

Python 3.11 or newer.
Git.
A local corpus you are allowed to process, or the repository's fixture corpus.
A terminal. The commands below include a Windows PowerShell path and a POSIX shell path where activation differs.

AuthorStyle 0.2.1 is published in the repository's v0.2.1 tag. The package declares the MIT license and supports Windows, macOS, and Linux through Python's normal environment model. The project is marked alpha in its package metadata, which matters when deciding how much to rely on generated output.

Install the tested version

Clone the repository and create an isolated virtual environment. Pinning the tag keeps the example aligned with the documented release instead of silently following unreleased main changes.

git clone --branch v0.2.1 https://github.com/paladini/authorstyle.git
cd authorstyle
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

On Windows PowerShell, activate the environment with:

git clone --branch v0.2.1 https://github.com/paladini/authorstyle.git
Set-Location authorstyle
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

The development extra installs the test tools in addition to the runtime dependencies. The optional embeddings and nlp extras are separate; the basic workflow does not require them.

Build a local profile

Start with a profile name and ingest the fixture corpus. A profile is stored below ~/.authorstyle/profiles/<profile_id>/ according to the README.

authorstyle init demo
authorstyle ingest demo ./fixtures/corpus/en
authorstyle corpus stats demo
authorstyle analyze demo
authorstyle profile show demo

On Windows PowerShell, the same commands use the installed console script:

authorstyle init demo
authorstyle ingest demo .\fixtures\corpus\en
authorstyle corpus stats demo
authorstyle analyze demo
authorstyle profile show demo

The repository's current fixtures produced three documents and seven chunks during verification. The exact counts will differ for your corpus. corpus stats reports documents, chunks, words, canonical families, and modes, while profile show summarizes the resulting global profile.

The important detail is the order. Ingestion normalizes and records source material, analysis builds the profile and Style Card, and the display commands let you inspect what was actually learned. You are not handing the tool a paragraph and asking it to guess a personality in one step.

What the Style Card measures

AuthorStyle combines explicit stylometry with pluggable style and semantic encoders. The documented methodology separates the two concepts: style describes how text is written, while semantic signals describe what it is about. The current methodology lists sentence and paragraph rhythm, punctuation rates, lexical diversity, Markdown structure, and technical prose or code ratios among the explicit features.

A generated Style Card can contain observations like these:

## Sentence rhythm
Typical sentences center around 18.0 words (q25=12.0, q75=24.0).
Evidence metrics: median_sentence_length

## Punctuation and typography
Notable punctuation rates: comma=4.20/100w, question=1.10/100w
Evidence metrics: punct_comma_per_100_words, punct_question_per_100_words

Those numbers are evidence about the supplied corpus, not universal facts about the author. If the corpus contains only API documentation, the profile may reflect that document type as much as the writer's broader voice.

Add a real corpus safely

AuthorStyle supports .md, .txt, .html, and .docx files. Markdown can include YAML front matter with fields such as title, date, language, and mode. A .authorstyleignore file can exclude paths using gitignore-style rules.

---
title: "A technical article"
date: 2025-04-02
source: devto
language: en
mode: technical
published: true
tags:
  - databases
---

Keep the corpus representative and permitted for local processing. Remove private documents that do not belong in the experiment, and keep source provenance intact so you can identify why a profile changed.

Generate and evaluate, with the boundary visible

After analysis, the documented commands for generation and evaluation are:

authorstyle write demo --prompt "Write about distributed databases"
authorstyle evaluate demo

Generation stores candidates, component scores, retrieved exemplars, and provider metadata for reproducibility. Evaluation uses document-level held-out splits, so chunks from one document are not placed in both profile and test sets. The project compares baselines such as generic, card, examples, hybrid, and full, and reports style distance, explicit stylometric fit, content adherence, naturalness heuristics, originality, and calibration percentiles.

Do not interpret a high score as proof that a passage is authentically yours. The repository explicitly warns that it models recurring patterns from the supplied corpus, does not guarantee topic-independent style transfer, and does not automatically infer beliefs or personality.

Privacy modes and security boundaries

The default LOCAL_ONLY mode permits only local or mock providers. REMOTE_PROFILE_ONLY sends the task and Style Card but not raw corpus excerpts. REMOTE_EXEMPLARS also sends selected exemplar passages. These are materially different boundaries, so choose the mode deliberately rather than treating a remote provider as an implementation detail.

The security policy also calls out prompt injection risks in Style Cards and generation prompts, unsafe file handling, accidental corpus disclosure, and unexpected network access when LOCAL_ONLY is configured. Never commit .env files, API keys, private corpora, or generated profile data unless you have a specific reason and have reviewed the consequences.

Reproducible verification

Run the project's test suite from the tagged checkout:

python -m pytest -q

The v0.2.1 checkout passed 24 tests in the verification environment. It also passed the CLI help command and the fixture path from initialization through analysis. Re-run those checks after changing dependencies or using a different Python version. A passing test suite validates the repository's current test cases; it does not validate the quality of your personal corpus or guarantee useful generated prose.

Common failure modes

The profile reflects the topic instead of the voice

This is a documented risk. Separate style and semantic embeddings help, but recurring subjects can still correlate with style signals. Add varied documents and inspect modes instead of treating one narrow corpus as a complete author model.

A mode has too little evidence

Mode profiles require matching front-matter metadata. The methodology says insufficient evidence triggers warnings and fallback toward the global profile. That fallback is safer than pretending a small sample is a reliable mode.

A remote provider receives too much

Review the configured privacy mode before running write. Start with LOCAL_ONLY when testing ingestion and analysis. Remote generation is optional and must be explicit.

The output copies a recognizable phrase

The project includes originality checks for long exact spans and word n-gram overlap. Inspect the overlap diagnostics and keep generated text under human review, especially when the corpus contains published or third-party material.

FAQ

Does AuthorStyle fine-tune an LLM?

No. The README describes a local research CLI with profiles, exemplars, encoders, candidate generation, scoring, and evaluation. Fine-tuning is not the documented quick-start path.

Can it infer my beliefs or persona?

No. Persona extraction is deferred in the current MVP. A style profile should not be treated as a biography.

Is it production-ready?

The package metadata marks the project as alpha. Treat it as an experiment that produces inspectable evidence and keep backups of any corpus or profile you care about.

Takeaway

The useful lesson in AuthorStyle is methodological: define style as measurable observations, keep the source corpus under a clear privacy boundary, and evaluate against held-out documents. That makes the experiment easier to inspect than a prompt-only imitation workflow, while still leaving room for the project's alpha-stage limitations.

If you try this with your own corpus, which verification signal would you trust first: sentence-level stylometry, document-level holdout evaluation, or originality diagnostics?

AI assistance disclosure: This tutorial was researched and drafted with AI assistance. Commands, project details, limitations, and verification results were checked against the public AuthorStyle repository, its tagged release, and a local test run before publication.

Turn Missing UI States into a CI Gate with unhappypath

Fernando Paladini — Tue, 20 Oct 2026 12:36:34 +0000

AI-assisted development makes it easy to finish the success case and forget everything that happens when the network is slow, the result is empty, a record is missing, or a user clicks twice. The application can look complete in a demo while real users still encounter blank screens and silent failures.

Those gaps are hard to review consistently. A code review may notice a missing loading state in one component and miss the same problem in another route. End-to-end tests can catch some failures, but they need a running application, test data, and carefully designed scenarios.

unhappypath takes a narrower approach. It statically scans a React or Next.js codebase, reports missing UI branches, and produces a deterministic score that can be used as a CI threshold. It does not run a browser or ask an LLM to judge the interface.

TL;DR

Build the current public repository, scan the included broken and good fixtures, and compare the results. The broken fixture scores 38/100 with 14 findings. The good fixture scores 100/100 with zero findings. Then add the min-score option to your own check so a change below your team's threshold exits with status 1.

What it checks

The current README describes four dimensions:

Routes: Next.js App Router loading, error, not-found, and global-error boundaries
Queries: loading, error, and empty states around data fetching
Mutations: failure handling and pending or disabled feedback for actions
Forms: submitting or pending feedback during submission

The scanner reports rule IDs such as RTE-01, RTE-02, RTE-03, QRY-01, QRY-02, QRY-03, FRM-01, and MUT-02. Each finding includes a file and line location, so the score is a triage signal rather than a replacement for reading the code.

The project is version 0.1.0 in its package metadata, uses TypeScript, requires Node.js 20 or newer, and declares the MIT license. The current default branch has no release tag and no package-lock file, so the commands below use the public main checkout and npm install.

Prerequisites

You need:

Node.js 20 or newer
npm and Git
A React or Next.js project to scan
A terminal that can read the source tree

The scanner is designed for source code, not a running server. It does not need credentials, a database, a browser, or network access to analyze the project.

Install and build from source

Clone the repository and build the CLI:

git clone https://github.com/paladini/unhappypath.git
cd unhappypath
npm install
npm run build

The compiled entry point is dist/cli.js. Check the current command surface:

node dist/cli.js --help

The documented invocation is:

node dist/cli.js /path/to/your-app

The path is optional and defaults to the current directory. The CLI also supports JSON, Markdown, min-score, badge, out, and quiet options.

Reproduce the broken and good scores

The repository includes two fixtures that make the behavior easy to verify without creating a sample application.

Run the intentionally incomplete fixture:

npm run demo:broken

The current output reports:

Score: 38/100
14 findings

It detects a Next.js App Router project, TanStack Query, and React. The findings include missing route boundaries, query states, a form submitting state, and an async button pending state.

Now run the covered fixture:

npm run demo:good

Its current output reports:

Score: 100/100
0 findings

The two demos give you a reproducible contract: the scanner distinguishes a fixture with deliberate gaps from one that includes the expected branches.

Scan your application

From the built checkout, scan a project root:

node dist/cli.js /path/to/your-next-app

Use JSON when another tool will consume the result:

node dist/cli.js /path/to/your-next-app --json --out unhappypath-report.json

A report contains the total score, dimension scores, detected technologies, and findings. A finding is intended to point you toward a code change. For example, a query finding may tell you that a useQuery call lacks a loading, error, or empty branch. A route finding may point to a missing loading.tsx, error.tsx, or not-found.tsx.

Do not treat a finding as proof that the user experience is poor. Static analysis can detect the presence or absence of recognizable branches, but it cannot judge whether the message is understandable, whether a retry really succeeds, or whether the layout remains usable on a small screen.

Turn the score into a CI gate

The useful automation boundary is the min-score option:

node dist/cli.js . --min-score 75

The documented exit behavior is:

0 when the score meets the threshold
1 when the score is below the threshold
2 for a usage error

The repository README also shows this GitHub Actions pattern:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npx unhappypath . --min-score 75

The npx example is a documented future path because the current README lists npm publishing as a roadmap item. Until a package is published, use the compiled local CLI in your own workflow:

- run: node unhappypath/dist/cli.js . --min-score 75

That command assumes the workflow has already cloned or built the scanner. Choose the threshold as a team policy. The README describes 75 as launchable and 90 as production UX, but those labels are project guidance, not a guarantee that an application is ready to ship.

Fix findings in a useful order

The README recommends fixing routes, queries, mutations, and forms in that order. Route-level boundaries can prevent a whole screen from becoming blank, while component-level feedback handles narrower interactions.

For a missing route loading state, add the convention expected by the framework:

app/
  dashboard/
    page.tsx
    loading.tsx
    error.tsx
    not-found.tsx

For a query, make the states explicit before rendering the successful result:

if (isPending) return <LoadingPanel />;
if (isError) return <RetryPanel onRetry={refetch} />;
if (!data?.length) return <EmptyPanel />;
return <Results items={data} />;

For a mutation or form, disable the action while the request is pending and show the user what is happening. The scanner can identify recognizable omissions, but the final copy and interaction still belong to your application.

Why a deterministic score helps

The tool intentionally avoids an LLM in the scanning loop. It uses filesystem discovery and TypeScript-oriented analysis, then produces the same kind of report for the same source tree. That makes a failing CI check easier to reproduce and review.

This keeps responsibility clear. The scanner finds candidate gaps. A developer decides whether a branch is required, fixes the code, and runs application tests that prove the behavior. unhappypath complements browser tests and manual QA; it does not replace them.

Limitations and security boundaries

The project is static analysis only. It does not run your app in a browser, simulate a slow network or a 500 response, verify UX copy, or prove that a retry action works. It currently focuses on the documented React and Next.js patterns. The roadmap lists Vue, Nuxt, SvelteKit, Remix conventions, MCP support, and npm publishing as future work.

Because it reads source files, run it only against directories you intend to inspect. It does not need network access for the scan, but dependencies still come from npm during installation. Pin and review dependencies according to your normal project policy.

Do not use the score as a security guarantee or as a substitute for accessibility, performance, integration, or end-to-end checks. A project can score well and still have a broken API, misleading error message, or inaccessible interaction.

FAQ

Does the scanner need a running Next.js app?

No. It scans source code and filesystem conventions.

Does it replace Playwright?

No. Use browser tests for runtime behavior. The scanner is a fast static complement.

Can I fail CI on findings instead of score?

The documented CLI gate is min-score. Choose a threshold that reflects the minimum coverage you want, then use the report to inspect individual findings.

Is npx unhappypath ready to use?

The current README labels npm publishing as a future option. Build from the repository until the project documents a published package.

Takeaway

A successful demo is only one UI state. Run unhappypath before calling an AI-built React or Next.js screen complete, use its file-and-line findings to guide fixes, and enforce a minimum score where a deterministic CI signal is useful. Then verify important paths with real tests and a browser.

What minimum score would be meaningful for your team: a first threshold around 75, a stricter 90, or a dimension-specific policy?

Disclosure: AI assistance was used to organize and edit this tutorial. The commands, version, output, limitations, and security boundaries were checked against the current public paladini/unhappypath README, package metadata, license, source checkout, and local build, test, and demo results.

Run a Safe Local Review of Env Team Vault Before Sharing .env Files

Fernando Paladini — Mon, 19 Oct 2026 22:00:33 +0000

Team environment variables are easy to share badly. A .env file sent through chat is convenient, but it is difficult to audit, easy to lose track of, and often contains more access than a teammate needs.

Env Team Vault is an open-source, self-hosted Node.js and TypeScript application that organizes teams, applications, variables, API tokens, and audit events around local development configuration. The useful question is not only how to install it. The useful question is whether the current code and package are ready for the boundary where you want to use them.

This tutorial shows a safe evaluation path for the current main branch and package version 1.0.0. You will build the project, inspect the CLI flow, and verify the environment-file route. This is a reproducible review, not a production recommendation.

TL;DR

Clone paladini/env-team-vault and install its locked dependencies.
Run the TypeScript build and inspect the CLI package before sending real values.
The project documents Docker Compose, a web UI, SQLite with Prisma, and env-team-vault sync.
The current root CLI imports axios, but axios is not declared in the root package.json, so the documented npx env-team-vault --help check currently fails after npm ci.
The API controller also has an unauthenticated compatibility branch. Treat the current code as a local-development experiment until that boundary is fixed and tested.

Prerequisites

You need Git, Node.js, npm, and a disposable working directory. The repository declares Node.js type definitions for Node 20, while its Dockerfile starts from Node 18 Alpine. Use a current supported Node release for the local build, and record the exact version in your review.

Do not put real API keys, production database URLs, or customer data into a first run. Use fake values and a disposable SQLite database.

1. Clone the current source and install it

The repository README documents Docker Compose and a manual npm setup. Use the owner repository URL, not the placeholder your-org URL in its copy-paste examples.

git clone https://github.com/paladini/env-team-vault.git
cd env-team-vault
npm ci

The lockfile pins the application package at version 1.0.0 and includes its Prisma, Express, Passport, SQLite session, and TypeScript dependency tree. npm ci tests the package as committed rather than silently resolving a new dependency graph.

Before continuing, inspect the installation result:

npm audit
npm run build

The build compiles src/main.ts and the application layers into dist. It does not prove that the web server is configured correctly, that the database has been initialized, or that the CLI can run. Keep those checks separate.

2. Understand the local architecture

The application combines Express with server-rendered EJS views. Prisma stores teams, users, applications, variables, API tokens, and audit logs in SQLite. The schema makes variable keys unique per application.

The main configuration values are:

NODE_ENV=development
PORT=3000
SESSION_SECRET=use-a-random-local-value
DATABASE_URL=file:./prod.db

The source defaults the HTTP port to 3000, enables the SQLite-backed session store, and uses a fallback session secret when SESSION_SECRET is absent. That fallback is convenient for a local experiment but is not an acceptable production setting.

The documented Docker path exposes port 3000 and persists the Prisma database and sessions in named volumes:

docker compose up -d

Open http://localhost:3000, register a disposable account, create a team, and create an application. Do not add a real secret while evaluating the flow.

3. Verify the documented CLI before trusting it

The README documents a sync command that writes the response into a local .env file:

npx env-team-vault sync <APP_ID> --url http://localhost:3000 --token <API_TOKEN>

The current root bin/cli.js imports axios, fs, yargs, and Node path utilities. The root package.json declares yargs and the other server dependencies, but it does not declare axios. A fresh npm ci followed by npx env-team-vault --help therefore reaches the CLI file and fails with Cannot find module 'axios'.

That failure separates a documented interface from a verified interface. Do not work around it by installing an undeclared package and then report the repository as working. A fix should add the dependency, update the lockfile, and add a smoke test for the executable path.

The CLI also writes the server response directly to .env in the current directory. That is convenient, but it can overwrite an existing file. Use a disposable directory until the command has a confirmed backup or safe-write policy.

4. Inspect the authentication boundary

The API route documented for the CLI is:

GET /api/vault/:appId

When an Authorization: Bearer ... header is present, VaultController looks up the API token, checks revocation, verifies team membership, verifies that the application belongs to that team, and records a SYNC_ENV audit event.

However, the same controller has an else branch for requests without an authorization header. It checks only that the application exists and then returns the environment content. The route is registered as a public Express route, without the authentication middleware used by other parts of the application.

This is the most important boundary in the current review. The README calls the project secure and audited, but the implementation currently permits an unauthenticated request for a known application ID. Do not expose this route to an untrusted network or put production secrets behind it. A safe contribution would remove the compatibility branch, require a valid token, add an integration test for unauthorized requests, and then document the changed contract.

This conclusion comes from the current controller and route source, not from treating the README's security language as a guarantee. Source behavior wins when documentation and implementation differ.

5. Verify the expected result without real secrets

For a local evaluation, the expected result is a buildable application and a reviewable data flow:

The server starts on port 3000 after the database has been initialized.
A disposable account can create a team and an application.
A fake variable such as DEMO_VALUE=not-a-secret can be associated with that application.
A valid API token can be used to request the application's .env representation.
The request creates an audit record when the token path is used.

The source formats the response as plain text, so a successful response should look like this:

DEMO_VALUE=not-a-secret

Check the HTTP status, response content type, and resulting file. Then inspect the audit log in the application. Never use a successful response as evidence that the deployment is safe by itself. The unauthenticated branch and the default session secret still need to be addressed.

Why this review order works

The order follows operational risk. npm ci and npm run build establish a baseline. The CLI check tests whether the documented command exists in the dependency graph. The controller review tests authorization before any real value crosses the boundary.

This is also why a green TypeScript build is not enough. TypeScript checks the files included in compilation. It does not guarantee that a JavaScript CLI has every runtime dependency, that a database migration exists, or that an HTTP route enforces the intended authorization policy.

Failure modes and honest limitations

The CLI reports a missing module

Confirm the package manifest and lockfile before installing anything manually. The current root CLI's undeclared axios import is a repository issue, not a user configuration error.

Prisma has no migration to apply

The current repository contains prisma/schema.prisma but no migration directory in the checked-in Prisma folder. Treat database initialization as a development setup step and review the resulting database before using the application. Do not point this first run at an existing production database.

A token request returns 401 or 403

Check the Bearer prefix, token revocation state, user team membership, and application team ownership. The controller intentionally rejects invalid or revoked tokens on the authenticated path.

You need production secret management

This project is explicitly positioned for local development variables. It is not a replacement for a mature production secret manager. The current unauthenticated route, fallback session secret, local SQLite storage, and missing CLI dependency are enough reason to keep the evaluation local and disposable.

FAQ

Is Env Team Vault a production secrets manager?

No. The README describes a self-hosted local-development tool, and the current route implementation has an unauthenticated compatibility path. Treat it as an experiment or contribution target until that behavior changes.

Why use `npm ci` instead of `npm install`?

npm ci uses the committed lockfile and exposes undeclared runtime dependencies more reliably. It makes the first verification closer to what a clean deployment or package consumer will see.

Should I publish the `.env` file generated by the CLI?

No. Keep it outside version control, use fake values while testing, and check your ignore rules before running a sync command in a repository.

Where is the source of truth for behavior?

Use the repository README for the documented workflow, then compare it with the package manifest, Prisma schema, CLI implementation, and vault controller for current behavior.

Takeaway

Env Team Vault has a clear local-development idea: keep team variables in one self-hosted application, expose a CLI, and record synchronization events. The responsible way to evaluate it is to verify each layer independently. The current build succeeds, but the documented CLI has an undeclared runtime dependency and the API has an unauthenticated response path. Those findings should shape how you use the project and what you fix next.

This tutorial was prepared with AI assistance for research organization and editorial review. The repository behavior, commands, and limitations were checked against the current public source and a fresh local checkout.

Would you use a tool like this for disposable development environments, and which authorization test would you add first?

Install and Validate a Reusable AI Agent Skill from GitHub

Fernando Paladini — Wed, 14 Oct 2026 12:35:27 +0000

AI assistants become easier to trust when their repeated work is packaged as a small, reviewable skill instead of copied into every prompt. The challenge is that an installed skill can influence future work, while a poorly structured repository can quietly add stale instructions, unsafe examples, or credentials.

This tutorial shows a practical installation and validation path using Fernando Paladini's agent-skills repository. The repository contains reusable skills for technical work, including a DEV.to publishing skill, plus sanitized MCP configuration examples. We will install one skill locally, inspect what it contains, and run the repository's documented checks without treating the project as a trusted executable.

TL;DR

Clone the repository, copy the devto-publish-expert directory into your agent's skills directory, then validate the skill and the committed MCP examples. The result is a reusable local capability with a visible instruction file, deterministic checks, and no need to commit real credentials.

Prerequisites

You need:

Git.
Python 3.11 or newer for the repository's TOML-aware validation script.
A local agent host that supports skills stored as directories with a SKILL.md entrypoint.
A writable skills directory for your agent.

The repository is public, non-archived, non-forked, non-empty, and MIT licensed. At the time of writing, its default branch is main and it does not publish a tagged release. That means this tutorial uses the current documented main workflow, not a versioned package contract. Pin a commit in your own automation if you need repeatable installation.

Install one skill

The repository README documents a focused installation model: copy only the skill directory you need. That keeps unrelated skills and configuration examples out of the runtime search path.

On macOS or Linux:

git clone https://github.com/paladini/agent-skills.git
cp -R agent-skills/skills/devto-publish-expert ~/.codex/skills/

On Windows PowerShell:

git clone https://github.com/paladini/agent-skills.git
Copy-Item -Recurse agent-skills\skills\devto-publish-expert $env:USERPROFILE\.codex\skills\

The copied directory should contain SKILL.md, a references/ directory, and the supporting scripts used by the skill. Restart the agent host after installation when it only discovers skills during startup. If your host uses another skills directory, adapt the destination while preserving the skill's internal layout.

The important boundary is that installation copies instructions and helper files. It does not grant the skill permission to publish, modify repositories, or access secrets. Those permissions come from the host and from the workflow that invokes the skill.

Validate the skill structure

The repository README separates skill validation from article validation. Use the Agent Skills validator supplied by your host or skill tooling, then run the repository's bundled unit tests for the skill scripts.

python path/to/skill-creator/scripts/quick_validate.py skills/devto-publish-expert
python -m unittest discover -s skills/devto-publish-expert/scripts -p "test_*.py"

The first command is structural validation. It should answer questions such as whether the skill has the expected entrypoint and layout. The second command checks deterministic helper behavior. These are different signals: a directory can be shaped correctly while a helper script still contains a regression.

For a local installation, also inspect the entrypoint before using it:

sed -n '1,220p' skills/devto-publish-expert/SKILL.md

On PowerShell, the equivalent is:

Get-Content .\skills\devto-publish-expert\SKILL.md -TotalCount 220

Read the instructions as policy, not as an authority escalation. A skill can describe a safe workflow, but the host still needs to enforce the final boundary around external writes.

Check sanitized MCP examples

The same repository stores example MCP configurations for restoring publishing workflows. Examples are useful only when a reader can distinguish placeholders from live authentication data.

Run the repository's configuration checker from its root:

python scripts/validate_mcp_configs.py

The checker expects three JSON examples and three TOML examples. It parses both formats, verifies the expected top-level server objects, looks for likely credential patterns, and requires the placeholder REPLACE_WITH_LOCAL_SECRET in .env.example. A successful check does not prove that an external account is configured correctly. It proves that the committed examples have the expected shape and do not contain obvious secrets.

If you adapt an example, keep the real value outside Git. For example, use a local environment file that is ignored by the repository, or configure the connector through your desktop agent's secret store. Never replace the placeholder in a public example and commit the result.

Expected result and reproducible verification

After installation, verification should leave you with three independently checkable facts:

The skill directory is present in the host's skills location.
The structural and helper checks complete without errors.
The MCP example checker accepts the repository's committed configuration samples.

You can record the exact source revision used for installation:

git -C agent-skills rev-parse HEAD
git -C agent-skills status --short

The first command gives you a commit to pin in documentation or automation. The second confirms that your clone has no local changes before you reason about its contents. Because the repository currently documents its workflow on main and has no release tag, this revision check is especially important for repeatable setup.

Why this works

The useful design choice is the narrow installation boundary. A skill is a directory with a clear entrypoint and optional references and scripts. Copying one directory makes the dependency visible and reviewable. It also avoids treating every file in a larger repository as an instruction that must be loaded for every task.

The validation split is equally important. Structure, helper behavior, and configuration safety are separate concerns. Keeping them as separate checks makes failures easier to interpret and reduces the temptation to declare a skill safe because one broad command happened to pass.

Failure modes and security boundaries

If the host does not discover the copied skill, check the destination path and restart the host. Do not duplicate the same skill under several locations until discovery happens; duplicate installations can make it unclear which revision is active.

If Python cannot parse the MCP checker, use a supported Python version rather than weakening the script or skipping validation. The checker imports tomllib, so the documented runtime should provide that module.

If validation reports a possible credential, stop and inspect the exact file. Do not suppress the warning just to obtain a green run. Remove the secret, restore the documented placeholder, rotate any exposed credential, and then validate again.

This workflow is local and reviewable, but it is not a security guarantee. A skill can still contain incorrect instructions, and a host can still grant excessive permissions. Review SKILL.md, pin the source commit, minimize connector scopes, and keep publishing or repository writes behind an explicit workflow gate.

FAQ

Do I need to install every skill?

No. Copy only the directory required by your workflow. Smaller installation scope makes updates and review simpler.

Is the current `main` branch a stable release?

No release tag was present when this tutorial was checked. Treat main as the current documented source and pin a commit when reproducibility matters.

Can the MCP examples be used with real credentials?

They can be adapted locally, but the committed examples are templates. Keep real credentials in a secret store or ignored local configuration and never publish them.

Does structural validation prove that the skill is correct?

No. It checks expected shape and selected helper behavior. Human review is still required for claims, permissions, and external side effects.

Takeaway

A reusable AI skill is easiest to maintain when installation, source revision, structure, helper behavior, and credential hygiene are all visible. Start with one directory, validate each boundary separately, and pin the commit before making it part of a repeatable agent workflow.

What additional check would you require before allowing a locally installed skill to perform an external write?

AI assistance disclosure: I used an AI assistant to organize this tutorial and check its Markdown structure. The repository facts, commands, and security boundaries are based on the current public source and documented examples linked above.

Install Active Admin Claude Theme 0.2.0 in Rails

Fernando Paladini — Mon, 12 Oct 2026 12:34:54 +0000

If an Active Admin backend works but still looks like a default admin panel, a theme gem can improve the interface without forcing a full frontend rewrite. The difficult part is choosing the correct integration path. Active Admin 3 uses Sass and Sprockets, while Active Admin 4 uses Tailwind CSS v4 and a different asset layout.

This tutorial installs activeadmin-claude-theme version 0.2.0 in a Rails application, explains the version-aware generator, and shows how to customize its tokens. The gem is a community project inspired by Claude aesthetics. It is not affiliated with or endorsed by Anthropic.

TL;DR

Add the gem to an existing Active Admin application, run rails generate activeadmin_claude_theme:install, rebuild CSS when using Active Admin 4, and verify the generated asset entry before restarting Rails. Active Admin 4 keeps dark mode and uses CSS variables. Active Admin 3 receives a Sass theme and light mode only.

Prerequisites

The release documentation lists these requirements:

Ruby 3.2 or newer
Rails 7.2 or newer
Active Admin 4.0.0.beta22 or newer for the Tailwind path
Active Admin 3.2 or newer for the Sass path
Node.js and the Active Admin npm toolchain for Active Admin 4

The project is distributed under the MIT license. The 0.2.0 release is available on GitHub and RubyGems. The gem declares runtime dependencies on Active Admin >= 3.2.0, < 5 and Rails >= 7.2.

This guide assumes that Active Admin is already installed. It does not replace the official Active Admin installation guide.

Install the theme in Active Admin 4

Active Admin 4 uses Tailwind CSS v4. The theme's release documentation uses 4.0.0.beta22 as its documented example, so keep the Active Admin and npm versions aligned with the application you are actually maintaining.

Add the gem to your Gemfile:

gem "activeadmin-claude-theme", "~> 0.2"

Install the bundle and run the generator:

bundle install
rails generate activeadmin_claude_theme:install

The generator detects Active Admin's major version. For Active Admin 4, it prepares the Tailwind entry and the theme assets. Rebuild the stylesheet and restart Rails:

npm run build:css
bin/rails server

The important detail is the separation between source and served CSS. The documented layout is:

app/assets/tailwind/active_admin.css
app/assets/builds/active_admin.css

The first file is the Tailwind source. The second is the generated stylesheet served by the application. If the source file is placed directly in the served Propshaft path, the build can produce confusing results or fail to expose the expected active_admin asset.

Install the theme in Active Admin 3

Active Admin 3 follows the Sprockets and Sass path. Add the same gem, but make sure the application has the Sass dependencies documented by the project:

gem "activeadmin", "~> 3.5"
gem "sprockets-rails"
gem "sassc-rails"
gem "devise"
gem "activeadmin-claude-theme", "~> 0.2"

Install the bundle and run the same generator:

bundle install
rails generate activeadmin_claude_theme:install

For Active Admin 3, the generator updates app/assets/stylesheets/active_admin.scss to use the theme entry:

@import "activeadmin_claude_theme/aa3/base";

Restart Rails after the asset change. Do not copy the Active Admin 4 Tailwind setup into an Active Admin 3 application. The two integration paths intentionally use different asset pipelines.

Customize the design tokens

The theme exposes a small set of semantic tokens instead of requiring selectors to be rewritten throughout the application. On Active Admin 4, override CSS variables after the theme import:

:root {
  --claude-primary: #d4845f;
  --claude-canvas: #fff8f0;
}

.dark {
  --claude-canvas: #121110;
}

On Active Admin 3, set Sass variables before importing the theme base:

$claude-primary: #d4845f;
$claude-canvas: #fff8f0;
@import "activeadmin_claude_theme/aa3/base";

The release's design reference documents the palette, typography, spacing, and token naming. The default primary color is #cc785c, the canvas is #faf9f5, and the semantic token prefix is --claude- for CSS variables.

Prefer semantic tokens for global changes. If a single screen needs a special treatment, use a narrow application-level selector rather than changing the theme's generated files. This keeps upgrades reviewable and makes it clear which choices belong to the application.

Verify the generated integration

After the generator finishes, verify the files before debugging the browser. For an Active Admin 4 application, check that the Tailwind source and build output exist:

Test-Path app/assets/tailwind/active_admin.css
Test-Path app/assets/builds/active_admin.css

On a Unix-like shell, the equivalent check is:

test -f app/assets/tailwind/active_admin.css
test -f app/assets/builds/active_admin.css

Then rebuild and inspect the generated CSS for one token that you changed:

npm run build:css
grep -n "claude-primary" app/assets/builds/active_admin.css

On Windows PowerShell, use this instead of grep:

Select-String -Path app/assets/builds/active_admin.css -Pattern "claude-primary"

For Active Admin 3, verify the Sass import and run the normal Rails asset precompile or development server path used by the host application:

grep -n "activeadmin_claude_theme/aa3/base" app/assets/stylesheets/active_admin.scss
bin/rails assets:precompile

The expected result is an Active Admin page using the theme's warm palette. On Active Admin 4, the built-in dark mode and mobile drawer remain Active Admin features. The theme's AA4 override map explains which partials the gem overrides and which hooks it deliberately preserves.

Common failure modes

The page is unstyled after installation

For Active Admin 4, run npm run build:css or the application's documented bin/rails css:build command, then restart Rails. Also confirm that the source is under app/assets/tailwind and the generated file is under app/assets/builds.

The generator changes the wrong file

The generator detects the installed Active Admin major version. Check the bundle before running it. An application with a stale or conflicting Active Admin dependency can be classified differently from what you expect.

Active Admin 3 reports a Sass error

Confirm that sassc-rails or a compatible Sass pipeline is installed and that the file imports activeadmin_claude_theme/aa3/base after your own variable overrides.

You expect dark mode on Active Admin 3

That is not supported by this release. The project documents dark mode for Active Admin 4 only because Active Admin 3 does not provide the same native dark-mode mechanism.

You treat the theme as an official Claude product

Do not. The README and FAQ explicitly describe it as a community theme. The name and visual inspiration do not provide any Anthropic affiliation, endorsement, security guarantee, or product compatibility promise.

FAQ

Can one Gemfile support both Active Admin 3 and 4?

The gem supports both major versions, but an individual application should use one Active Admin integration path at a time. The project's own development setup uses separate dummy applications and dependency files for its version coverage.

Does the theme replace all Active Admin templates?

No. The AA4 documentation describes minimal partial overrides and preserved Active Admin hooks. It remaps Tailwind colors, adds semantic tokens, and customizes selected header and navigation partials.

Can I use it with Propshaft?

The FAQ documents Propshaft support for Active Admin 4 when the standard Tailwind and cssbundling setup is followed. Active Admin 3 typically remains on Sprockets.

What should I customize first?

Start with --claude-primary and --claude-canvas on Active Admin 4, or their Sass equivalents on Active Admin 3. These two choices demonstrate the token flow without coupling your application to internal selectors.

Takeaway

The useful part of activeadmin-claude-theme is not only its palette. Its version-aware generator makes the Active Admin 3 and 4 boundary explicit, while its token model gives Rails teams a small, reviewable customization surface. Install against the release that matches your application, verify the generated asset path, and treat Active Admin 3 and 4 as separate pipelines.

Have you kept one Active Admin application compatible with both major asset pipelines, or did you choose a clean upgrade to Active Admin 4? Share the constraint that shaped the decision.

AI assistance disclosure: AI assistance was used to organize this tutorial and draft prose. Project behavior, versions, commands, limitations, and links were checked against the public repository, the v0.2.0 release, the gem metadata, and the project documentation.

Score Any Public Repository Reproducibly with harness-maturity-analysis

Fernando Paladini — Sun, 11 Oct 2026 12:31:02 +0000

If you are evaluating how well a repository supports AI-assisted development, it is easy to mix two different jobs: measuring one repository quickly and adding a research observation to a maintained corpus. Those jobs need different levels of evidence.

harness-maturity-analysis gives you both paths. Its corpus workflow pins repositories to exact commits and records scanner versions. Its ad hoc command lets you inspect any local path or public repository without writing to the corpus.

This tutorial focuses on the second path. You will run a deterministic local score, read the dimension breakdown, identify the highest-value gaps, and understand what the result does not prove.

TL;DR

Clone the project, install its development dependencies, then run the documented score script with a repository URL or local path:

git clone https://github.com/paladini/harness-maturity-analysis
cd harness-maturity-analysis
npm install
npm run score -- https://github.com/owner/repo

The command prints a maturity level, a point total, dimension percentages, detected tooling, and several unmet checks. It does not add the target to corpus/manifest.json or create a generated report under corpus/reports/.

Prerequisites

You need Git, Node.js 18 or newer, and npm. The project declares the Node engine requirement in package.json. A network connection is needed when you pass a remote repository URL because the runner must obtain the source and the pinned scanner package.

The project is MIT licensed. Read the repository license before incorporating the scripts into another workflow.

The current public README documents harness-score@1.8.1 as the scanner pin used by the corpus. That version is part of the research evidence, not a promise that every future run will produce the same number if the target repository changes.

Run an ad hoc score

From the project directory, pass either a GitHub URL or a local directory:

npm run score -- https://github.com/owner/repo
npm run score -- C:\path\to\local\repository

The first command asks the project to obtain the remote source. The second analyzes files already on disk. In both cases, the ad hoc runner reads the target and sends it to the scanner; it does not install dependencies or execute code from the repository being inspected. That boundary matters when the target is unfamiliar.

For a first experiment, score the analysis project itself:

npm run score -- .

The score npm script delegates to corpus/score-adhoc.mjs. The script uses the study's configured scanner version, prints the score and dimension breakdown, and lists unmet checks that may offer the clearest improvement opportunities.

Understand the output

A result has several separate signals. The maturity level is a compact interpretation of the score. The point total explains how much of the available model the repository satisfies. Dimension percentages show whether the result is driven by context, skills, guardrails, feedback, CI, or hygiene.

The detected-tooling line is descriptive. If the scanner identifies editor or agent configuration, that tells you which signals were found in the inspected files. It does not certify that a team uses the tools effectively.

The unmet checks are a prioritization aid, not a backlog generated by an oracle. A missing type-checking check, for example, may be a reasonable next experiment for a JavaScript project, but it is not automatically a defect for every repository. Read the check definition and the relevant files before changing anything.

The project's methodology makes the same distinction for the larger study: the score describes a repository's harness, not the competence of the organization that owns it. A low score can be appropriate for a library that was never designed as an agent-first workspace.

Reproduce the observation

An ad hoc score is useful for exploration, but a research claim needs stronger identity. Record at least these values alongside the output:

the repository URL;
the commit SHA or tag inspected;
the scanner version;
the command and options used;
the complete output;
the date and environment.

Then rerun the same command at the same commit. If the score changes, investigate the scanner version, checkout contents, platform-specific files, and command arguments before interpreting the difference.

The corpus workflow formalizes this process. corpus/manifest.json stores exact repository commits and the scanner version. corpus/run.mjs clones pinned source into a cache, scans it, and writes generated reports. The generated artifacts are then rebuilt from those reports instead of being edited by hand.

That separation is the key design choice: use npm run score -- ... when you are asking, "How does this repository look right now?" Use the corpus workflow when you are ready to make a durable, reviewable data point.

Verify the local installation

Before trusting a local checkout, run the project's own checks:

npm test
npm run lint

The test suite covers parsing, manifest shape, selection logic, report generation, history handling, site rendering, and clone behavior. Linting checks the JavaScript and data files with Biome. These checks validate the analysis tool itself; they do not validate the quality of the repository you pass to npm run score.

After a score, check the working tree:

git status --short

For an ad hoc run, the expected result is no new corpus entry or generated report. If you intended to create study evidence and see unexpected files, stop and inspect the command and repository state before continuing.

Failure modes and security boundaries

The target is not reproducible

A branch name points to moving content. Prefer a commit SHA or release tag when comparing results over time. A score from main is a current snapshot, not a permanent fact.

The score looks surprisingly high or low

Read the file-level evidence and check whether the project type matches the model's assumptions. The study explicitly warns that a repository-local harness score should not be treated as an organizational ranking.

The remote checkout cannot be obtained

Check the URL, visibility, network access, and Git installation. Do not work around the failure by copying generated reports from another checkout. A missing checkout is missing evidence.

You are tempted to run target code

Do not. The documented runner is designed to inspect files without executing code from the scanned repository. Keep that boundary intact, especially for untrusted projects, and treat any workflow that installs target dependencies as a different security model.

The corpus changes unexpectedly

Do not hand-edit corpus/reports/, results/, or the Pages site. Those files are generated. Re-run the documented generator after changing an input, then review the diff.

FAQ

Does an ad hoc score change the public corpus?

No. It is intended for a one-off reading. Corpus additions require a separate pinned and reviewable workflow.

Can I compare two projects directly?

You can compare their outputs as an exploratory exercise, but keep repository type, commit identity, scanner version, and checkout conditions visible. The number alone is not a universal quality ranking.

Does L4 mean the repository is production-ready?

No. It means the inspected files satisfy the model's harness checks at that snapshot. It says nothing by itself about correctness, reliability, maintainability, licensing of dependencies, or operational safety.

Is this an AI judge?

The scanner is deterministic and filesystem-oriented. It does not replace human review, and the repository's research protocol treats blind human assessment as a separate question.

Takeaway

Use the ad hoc command to ask a focused question without polluting research history. Pin the target and scanner when the result needs to be reproduced. Most importantly, read the evidence behind the number before turning a maturity score into a technical decision.

What repository would you score first, and which scanner signal would you want to validate manually before trusting the result?

AI assistance disclosure: AI was used to help organize and edit this tutorial. Repository behavior, commands, versions, and limitations were checked against the project's public source and local verification output.

Customize Active Admin with CSS Design Tokens and Mobile Navigation

Fernando Paladini — Sat, 10 Oct 2026 12:37:29 +0000

If an Active Admin interface works but still feels like an internal tool from another decade, replacing the entire admin stack is usually too expensive. The smaller move is to change the visual system around the screens you already have.

This tutorial shows how to use Active Admin AAA Theme as a Rails theme and then customize its CSS design tokens. The useful idea is not the Apple-inspired visual language itself. It is the separation between the theme structure and the values you are likely to change: colors, type, spacing, radiuses, and shadows.

The repository currently identifies itself as version 0.1.0, requires Ruby 3.0 or newer, and declares Rails 6.1 or newer plus Active Admin 3.0 or newer as gem dependencies. It is public, MIT licensed, and has no published GitHub release or RubyGems package at the time of writing. Treat the current branch as an early project, not as a stability guarantee. The version and dependency claims come from the version file and gemspec.

TL;DR

Add the theme gem to a Rails application, import its stylesheet and JavaScript entrypoints, then override the --aaa-* variables in your own stylesheet. Verify the result in both light and dark color schemes, and check the mobile menu before treating the change as complete.

Prerequisites

You need:

A Rails application that already uses Active Admin.
Ruby 3.0 or newer.
Rails 6.1 or newer and Active Admin 3.0 or newer.
Bundler and an asset pipeline or JavaScript setup that can load the documented imports.
A way to inspect the admin UI at desktop and mobile widths.

The theme is a presentation layer. It does not replace Active Admin authentication, authorization, database models, filters, or resource definitions. Keep those responsibilities in your application.

Install the theme

Add the gem name from the project's current README to your application's Gemfile:

gem 'activeadmin-aaa-theme'

Install dependencies:

bundle install

The repository's gemspec declares the Rails and Active Admin dependencies, while the package metadata reports the same project version, 0.1.0. Because the gem is not currently published to RubyGems, a real application may need to point Bundler at the source repository or use a locally built gem until a package is released. Do not assume that the short gem name resolves from RubyGems today.

Connect the stylesheet and JavaScript

The README asks you to replace the default Active Admin stylesheet import in app/assets/stylesheets/active_admin.scss:

// Remove the default Active Admin base stylesheet
// @import "active_admin/base";

// Load the AAA theme
@import "active_admin/aaa_theme";

Then load the theme JavaScript from your Active Admin entrypoint:

import "active_admin/aaa_theme";

The JavaScript is intentionally small. On DOMContentLoaded, it looks for Active Admin's #header, creates a button with the aaa-menu-toggle class, and toggles menu-open on the header when the button is clicked. It also closes the menu when a click happens outside the header. You can inspect this behavior in the theme JavaScript source.

This means the import is not decorative. If the stylesheet loads but the JavaScript entrypoint does not, desktop styling can appear correct while the mobile navigation remains incomplete.

Customize the design tokens

The theme defines CSS custom properties under :root. Put your overrides after the theme import so your application stylesheet wins in the cascade:

@import "active_admin/aaa_theme";

:root {
  --aaa-primary-h: 260;
  --aaa-primary-s: 85%;
  --aaa-primary-l: 55%;
  --aaa-border-radius-lg: 8px;
  --aaa-font-family: "Helvetica Neue", Arial, sans-serif;
}

The current README documents tokens for the primary color, page and card backgrounds, primary text, medium and large radiuses, and body and display font stacks. The source stylesheet also defines transition values, sidebar width, border colors, shadows, and status colors. This gives you two useful levels of customization:

Change a few variables to match an existing product identity.
Fork or extend selectors only when the structure itself needs to change.

Start with tokens. Selector overrides are more coupled to Active Admin's generated HTML and are therefore more likely to need maintenance after an Active Admin upgrade.

Understand dark mode before overriding colors

The theme has two dark-mode paths. First, a prefers-color-scheme: dark media query changes background, text, border, shadow, and primary-lightness variables. Second, body.dark applies a similar palette when your application explicitly adds the class.

That gives you a simple verification matrix:

Light system preference with no dark class.
Dark system preference with no dark class.
Light preference with body.dark.
A mobile viewport with the menu closed and open.

Do not override only --aaa-bg-base and assume dark mode is handled. Check text, borders, focus rings, links, flash messages, tables, and form controls as well. A readable dashboard can still have an inaccessible input or a low-contrast action link.

Verify the result reproducibly

Run the normal dependency and application setup commands documented by your Rails application. If you are using the repository's dummy application, its contribution guide points to the standard Rails database setup and server commands.

After the application boots, verify the theme in the browser:

Open an Active Admin index page with a table and filters.
Confirm that the stylesheet import changes the sidebar, title bar, cards, tables, and controls.
Use browser developer tools to inspect :root and confirm that your overridden --aaa-* values are active.
Switch the operating system or browser color preference to dark and repeat the inspection.
Reduce the viewport below the theme's mobile breakpoint and click the generated menu button.
Click outside the header and confirm that the menu closes.

For a source-level check, compare your built asset output with the theme's SCSS entrypoint and JavaScript entrypoint. This catches a missing import without confusing it with a CSS specificity issue.

Failure modes and tradeoffs

The gem cannot be found

The repository currently has no RubyGems release even though the README includes a Gem Version badge. Check the package source before debugging Bundler. Until a release exists, use the source repository or a locally built gem according to your organization's dependency policy.

The menu button does not appear

Check that the JavaScript import is part of the entrypoint loaded by the Active Admin layout. The script exits without creating a button when it cannot find #header, so a wrong page, an earlier script failure, or a changed Active Admin layout can all produce the same symptom.

The color override has no effect

Confirm that the override is loaded after the theme and that the variable name is exact. Inspect the computed value rather than only searching the source file. A selector that sets a concrete color can also win over a variable-based declaration.

A table becomes hard to use on mobile

The theme adds responsive behavior, but it cannot make every wide Active Admin table fit a narrow screen. Test real resources with realistic column names and action links. Keep horizontal scrolling available where the data cannot be meaningfully collapsed.

Security boundaries

This theme changes CSS, HTML-adjacent behavior, and a small client-side menu controller. It does not provide authorization, secure sessions, CSRF protection, input validation, or protection from unsafe Active Admin resource definitions. Continue to use Rails and Active Admin security controls, review the generated asset policy, and treat third-party font loading as a separate privacy and availability decision.

The README imports Google Fonts in the theme stylesheet. If your admin area must remain self-contained or avoid third-party requests, remove that import and provide local font fallbacks. The theme's MIT license permits reuse subject to its license terms, but it does not turn the project into a security-reviewed dependency.

FAQ

Does this replace Active Admin?

No. It is a theme gem that styles an existing Active Admin installation.

Can I use my own brand colors?

Yes. The documented CSS custom properties are the intended starting point for primary colors, typography, radiuses, and related visual values.

Does dark mode require a JavaScript framework?

No. Automatic dark mode uses the CSS media query, and manual dark mode uses a dark class on the body. The small JavaScript entrypoint is for the responsive navigation toggle.

Is version `0.1.0` a stable release?

No. It is the version declared in the repository's source. There is no published GitHub release or RubyGems package to treat as a stable distribution.

Takeaway

The practical value of Active Admin AAA Theme is its tokenized boundary: install the theme once, keep application-specific branding in your own stylesheet, and verify desktop, dark mode, and mobile behavior as separate states. That approach makes visual customization easier to review and gives you a clear place to look when an upgrade changes the admin markup.

If you try this pattern, which token or Active Admin component would you want the theme to expose next: navigation spacing, table density, form controls, or accessibility-focused color presets?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. Project facts, examples, limitations, and links were checked against the public repository sources listed in the article on October 10, 2026.

Add an Evidence-Backed Repository Listing to Harness Maturity Showcase

Fernando Paladini — Thu, 08 Oct 2026 12:36:27 +0000

If you publish a maturity score for an open-source repository, readers need more than a number. They need to know which commit was measured, which scanner produced the result, and where the raw evidence can be inspected.

Harness Maturity Showcase is a small static site that makes those checks visible. It stores repository listings as data, links each listing to public evidence, and validates the rules in CI. This tutorial shows how to add one reproducible full report without changing the site's ranking code.

TL;DR

You will scan a public repository with the published harness-score package, commit the generated JSON report to that repository, add one record to data/projects.json, and run the showcase's deterministic checks. The important part is the evidence chain: repository, measured commit, scanner version, score, and public report must agree.

Prerequisites

You need:

Git and a GitHub account.
Node.js 20 or newer. The showcase declares node >=20.
A public GitHub repository that you are allowed to scan and modify.
Permission to open a pull request in your fork of the showcase.

The showcase is MIT-licensed. It is a static HTML, CSS, and JavaScript site with no runtime dependencies. Its own checks run with Node's built-in test runner.

Understand the two contribution paths

The project supports two kinds of entry. A full report participates in the numeric ranking. It includes score, maxScore, level, toolVersion, a measured commit SHA, and a link to a committed JSON report.

A badge-only entry is different. It records a public maturity claim from a repository README, but it does not claim a numeric score. The validator rejects badge entries that include score or maxScore.

Use the full-report path when you can publish the scanner output and identify the exact commit. Use badge-only when the repository displays an official badge but does not publish a full report. Do not turn a badge claim into a measured result by inference.

1. Start from a clean checkout

Create a working copy of the repository you want to measure. The scanner reads files, so the result should be tied to a commit that another person can retrieve later.

git clone https://github.com/your-name/your-project.git
cd your-project
git checkout --detach YOUR_COMMIT_SHA
git rev-parse HEAD

Record the 40-character SHA printed by the final command. The showcase compares reports within the same scanner version and stores the measured commit for reproducibility.

The current showcase refresh documents the same rule: reports are pinned to public default-branch commits, and future refreshes use a new dated directory instead of rewriting historical evidence.

2. Generate the report with the published scanner

Run the published package from outside the repository checkout. The documented command writes JSON to standard output and leaves the scanned project unchanged.

mkdir -p reports
npx --yes harness-score@1.8.1 /path/to/pinned-checkout --json > reports/harness-score.json

On Windows PowerShell, the equivalent redirection is:

New-Item -ItemType Directory -Force reports | Out-Null
npx --yes harness-score@1.8.1 C:\path\to\pinned-checkout --json | Out-File -Encoding utf8 reports\harness-score.json

Use the version that you actually ran in the showcase record. Do not copy a score from a different scanner version. The current release reports version 1.8.1, and the package requires Node.js 18 or newer; the showcase itself requires Node.js 20 or newer.

Inspect the report before committing it. Confirm that its tool.version, level, score, maximum score, and measured commit describe the checkout you intended to scan.

3. Publish the evidence in the scanned repository

Commit the report to the repository you measured. A simple layout is enough:

.
└── harness-score.json

git add harness-score.json
git commit -m "Add Harness Score evidence"
git push origin YOUR_BRANCH

The report URL in the showcase must be public and stable, for example:

https://github.com/your-name/your-project/blob/main/harness-score.json

If you measure a historical commit, link to the report at that commit or to a branch that preserves the exact JSON. A link that later changes to a different report weakens the evidence chain.

4. Add one full-report record

Fork the showcase, edit data/projects.json, and add one object. The contribution guide requires source: "study" for a full report.

{
  "repo": "your-name/your-project",
  "category": "community",
  "level": 3,
  "score": 82,
  "maxScore": 105,
  "toolVersion": "1.8.1",
  "commit": "0123456789abcdef0123456789abcdef01234567",
  "source": "study",
  "evidence": "https://github.com/your-name/your-project/blob/main/harness-score.json"
}

Replace every illustrative value with the corresponding value from your report. The repository name must use owner/name syntax, and each repository may appear only once. The commit must be a complete 40-character hexadecimal SHA.

The category field is part of the site's data model, while the validator focuses on the repository name, source, numeric fields, commit, scanner version, and evidence URL. Keep the record small and avoid adding claims that the report does not contain.

5. Validate before opening the pull request

From the showcase checkout, install its lockfile and run the documented check:

npm ci
npm run check

The check script runs npm run validate and npm test. Validation checks repository names, duplicates, levels from 0 through 4, numeric bounds, scanner versions, complete commit SHAs, public GitHub evidence links, and the badge-only rules.

The test suite checks the page structure, report reproducibility links, scanner-version boundaries, historical rankings, and the separation between full reports and badge-only entries. A passing check confirms the repository's data and site invariants. It does not replace human review of the evidence URL.

Open a focused pull request that changes one listing. Maintainers verify that the linked evidence is public and that the values in data/projects.json match it. If the measured repository changes substantially, generate a new report rather than silently editing the old one.

Why the evidence model matters

A score without a commit is hard to reproduce. A score without a scanner version is hard to compare. A score without a public report asks reviewers to trust a summary they cannot inspect.

The showcase keeps those concerns separate. Rankings are scoped to a scanner version, full reports point to immutable evidence, and badge-only records stay outside numeric ranking. This makes a lower score interpretable: it may reflect the repository, the scanner version, or the measured commit, and the data tells you which inputs to investigate.

The same design also limits what the site can claim. A passing GitHub Actions job proves that the data satisfies structural checks. It does not prove that a repository is secure, production-ready, or better than another project in every engineering dimension.

Failure modes and honest limits

The report is rejected because the commit is invalid

Check that commit contains exactly 40 hexadecimal characters. Do not use a short SHA, a branch name, or the commit that happened after the scan.

A full report does not appear in the ranking

Confirm that source is study, that toolVersion is a semantic version, and that score and maxScore are numbers within bounds. Badge-only entries intentionally do not receive numeric ranking.

The score changed after a refresh

Compare the scanner version, measured commit, and repository contents. The project documents that changes between scanner versions or repository revisions are not, by themselves, evidence of improvement or regression.

The site check passes but the evidence is wrong

This is a review failure, not a validator failure. Open the evidence URL, compare the JSON fields with the record, and verify that the URL is public before asking for review.

Security boundary

The scanner is a read-only file inspection tool for this workflow, but running any package still deserves normal supply-chain care. Pin the version in reproducible instructions, review the package source and lockfile policy appropriate to your environment, and do not scan private repositories or publish sensitive report contents without authorization.

FAQ

Can I submit a private repository?

No. The evidence URL must be public, and the showcase is designed for inspectable open-source data.

Can I submit a score from an older Harness Score version?

Yes, when the report and metadata satisfy the schema, but rankings are separated by scanner version. Use the current published version for a new contribution unless you have a reason to preserve historical evidence.

Does a passing score make a repository mature?

It measures the checks implemented by Harness Score. It does not certify software quality, security, or operational readiness.

Can I add several repositories in one pull request?

The contribution guide asks contributors to keep a submission focused on one repository. Follow that review boundary unless maintainers ask for a batch change.

Takeaway

The useful unit is not a maturity number. It is a number connected to a scanner version, a measured commit, a public report, and a validation path that another contributor can repeat.

If you maintain an open-source repository with an official Harness Score result, submit the smallest complete evidence record you can defend. What additional evidence would make a maturity listing more useful to you: historical snapshots, CI status, or a clearer explanation of each check?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, project behavior, version claims, and validation results were checked against the cited repository, its current documentation, and the published package metadata.

Use mcp-me v0.6.0 to Share One Local AI Profile Across MCP Clients

Fernando Paladini — Wed, 07 Oct 2026 12:38:11 +0000

TL;DR

If you use more than one MCP-compatible AI client, repeating your background in every tool is tedious and easy to get wrong. mcp-me v0.6.0 gives you one local profile directory, a YAML configuration file, and an MCP server that clients can read.

This tutorial creates the profile, validates it, configures the same server for Cursor, VS Code, and Windsurf, and explains where Claude Desktop fits. The setup uses the published mcp-me@0.6.0 package, not an unreleased checkout.

Prerequisites

You need:

Node.js 20 or later. The package declares node >=20.0.0 in its release metadata.
npm and a terminal.
One MCP-compatible client such as Cursor, VS Code with GitHub Copilot, Windsurf, or Claude Desktop.

The project is open source under the MIT license. The v0.6.0 release is the stable reference for this walkthrough, and the package manifest records the version and Node.js requirement.

Create and validate one profile

You can run the CLI without a global installation through npx. This keeps the example tied to the exact version used in the tutorial.

npx --yes mcp-me@0.6.0 init
npx --yes mcp-me@0.6.0 validate

With no directory argument, v0.6.0 uses ~/.mcp-me as the default profile location. The init command creates the YAML templates, .mcp-me.yaml, and agent instruction files. The validate command checks the profile YAML files against the project's schemas.

The command output should end with a successful validation message for the profile files. In a clean smoke test, the release created 11 files and validated identity, career, skills, interests, personality, goals, projects, and FAQ data.

Now inspect the generated configuration:

cat ~/.mcp-me/.mcp-me.yaml

On Windows PowerShell, use this equivalent command:

Get-Content "$HOME\.mcp-me\.mcp-me.yaml"

The file separates data generators from live plugins. Start with a small configuration and replace the example values with your own public handles:

generators:
  github: your-username
  devto: your-username

plugins:
  github:
    enabled: true
    username: your-username

The configuration is not your profile data. It tells mcp-me which sources to use when it generates profile files and which live plugins should be available to the server. Keep the generated YAML files reviewable, and validate after editing.

Generate profile data locally

After editing .mcp-me.yaml, run the generator:

npx --yes mcp-me@0.6.0 generate
npx --yes mcp-me@0.6.0 validate

The v0.6.0 README documents username-based generators and the default profile path. Many public sources do not need API keys, but that is source-dependent. A provider can still require authentication, rate limits, or a local export. Treat each generated file as data to review before making it available to an assistant.

If you want an isolated profile for a project or experiment, pass a directory explicitly instead of changing the default:

npx --yes mcp-me@0.6.0 init ./my-ai-profile
npx --yes mcp-me@0.6.0 validate ./my-ai-profile
npx --yes mcp-me@0.6.0 generate ./my-ai-profile

This explicit path is useful for testing because it makes the data boundary obvious. It also lets you keep separate profiles for work and personal use.

Connect the same server to multiple clients

The important idea is that every client points to the same command and profile directory. The server reads the profile when it starts, so the clients do not need separate copies of your YAML files.

The simplest cross-client command is:

npx -y mcp-me serve

For Windsurf, add an entry to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "me": {
      "command": "npx",
      "args": ["-y", "mcp-me", "serve"]
    }
  }
}

For Cursor, place the same server entry in .cursor/mcp.json in a project, or in the client configuration used for global servers:

{
  "mcpServers": {
    "me": {
      "command": "npx",
      "args": ["-y", "mcp-me", "serve"]
    }
  }
}

VS Code uses a different top-level key. In .vscode/mcp.json, use servers:

{
  "servers": {
    "me": {
      "command": "npx",
      "args": ["-y", "mcp-me", "serve"]
    }
  }
}

These client examples are taken from the v0.6.0 README configuration section. Claude Desktop can use the .mcpb asset attached to the v0.6.0 GitHub release, or the manual MCP configuration documented by the project.

Verify the server boundary

Before connecting a client, ask the CLI for help and validate the profile again:

npx --yes mcp-me@0.6.0 --help
npx --yes mcp-me@0.6.0 validate

Then start the server in a terminal:

npx --yes mcp-me@0.6.0 serve

An MCP client normally launches this process itself over standard input and output. The useful verification is therefore client-side: connect the me server, ask the client to read a profile resource, and confirm that the answer matches the YAML you reviewed. Do not treat a successful process launch as proof that every generator or plugin works.

If you need to make the profile location explicit, set MCP_ME_PROFILE_DIR in the client process environment or pass a directory to the serve command. The release README documents both options.

Why this works

The profile files and the .mcp-me.yaml configuration form a local source of context. The MCP server exposes that context through the protocol, while each client remains responsible for deciding when to read it. This is different from copying a long instruction block into every client: the data has one canonical location, and changes can be reviewed with normal file tools.

The design also leaves a useful boundary between generated data and live integrations. Generated YAML can be inspected before use. Plugins can provide current values when an assistant queries them. That separation makes it easier to disable a plugin, remove a field, or keep a sensitive category out of a profile.

Failure modes and limitations

The client cannot find `npx`

GUI applications may not inherit the same PATH as your terminal. Check the client documentation for environment configuration, or use the absolute path to your Node.js installation. The error is a process discovery problem, not a profile validation failure.

Validation fails after editing YAML

Run validate with the profile directory and read the first reported file. Fix the schema or value, then run validation again. Do not connect an unvalidated profile and assume the client will explain the problem.

A source returns incomplete data

Generators depend on the source's public API, feed, or export format. A valid local profile does not prove that a remote source returned complete data. Review the generated file and consult the source-specific documentation before relying on it.

Local does not mean risk-free

The project is designed around local YAML files, but any MCP client that can read those files may place their contents into model context. Do not put passwords, private keys, access tokens, or secrets in the profile. Use the project's documented plugin settings and your operating system's file permissions. The MIT license and local execution do not constitute a security guarantee.

The tutorial also uses the stable v0.6.0 release. The repository's default branch may contain newer or unreleased behavior, so check the current changelog before copying commands into a new environment.

FAQ

Do I need to install `mcp-me` globally?

No. npx --yes mcp-me@0.6.0 is enough for the commands above. A global npm installation is convenient for repeated use, but pinning the version makes a tutorial and a reproducible check clearer.

Can different clients use different profiles?

Yes. Pass an explicit directory or set MCP_ME_PROFILE_DIR for a client process. Use separate profiles when the audiences or sensitivity of the data differ.

Does `mcp-me` remember previous conversations?

No. It exposes profile data and configured live resources through MCP. Conversation history, model behavior, and client-side context policies remain separate concerns.

Takeaway

Use one reviewed profile directory as the shared context layer, validate it after every edit, and point each MCP client at the same mcp-me serve command. Start with public, low-risk fields. Add generators and plugins only when you understand what data they read and what the client can send to a model.

What is the first profile category you would keep local and shared across your AI tools: skills, projects, career history, or something else?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, version claims, configuration examples, and smoke-test result were checked against the mcp-me v0.6.0 release and its primary project documentation.

DEV Community: Fernando Paladini

Stop Guessing localhost Ports with portmap and TypeScript

TL;DR

Prerequisites

Build portmap from the repository

Run a static topology check

Use the result in a real project

Add a read-only MCP server

Why the reconciliation is useful

CI verification

Failure modes and security boundaries

Reproducible verification

FAQ

Does portmap replace Docker or a process manager?

Does it require an AI model?

Can I install it from npm today?

Should .portmap.json be committed?

Takeaway

Build a Mobile Guitar Tuner with React, Express, and PostgreSQL

TL;DR

Prerequisites

Start PostgreSQL locally

Install and configure the app

Apply the database schema and run the app

What the current code actually provides

Reproducible verification

Failure modes and boundaries

PostgreSQL does not start

The browser cannot access audio features

Database changes appear not to persist

Development credentials leak into deployment

FAQ

Can I run it without Docker?

Is there a stable release to pin?

Is this a production-ready authentication system?

Takeaway

AI assistance disclosure

Turn Spec Drift into a Pull Request Check with SpecGov

TL;DR

What you will build

Prerequisites

Install the stable CLI

Add a small manifest

Run the local checks

Add the GitHub Action

Why this works

Failure modes and limitations

FAQ

Does SpecGov require GitHub?

Does it support only one specification framework?

Should every repository start in strict mode?

Does a warning mean the code is unsafe?

Takeaway

Learn Your Writing Style Locally with AuthorStyle and Python

TL;DR

Prerequisites

Install the tested version

Build a local profile

What the Style Card measures

Add a real corpus safely

Generate and evaluate, with the boundary visible

Privacy modes and security boundaries

Reproducible verification

Common failure modes

The profile reflects the topic instead of the voice

A mode has too little evidence

A remote provider receives too much

The output copies a recognizable phrase

FAQ

Does AuthorStyle fine-tune an LLM?

Can it infer my beliefs or persona?

Is it production-ready?

Takeaway

Turn Missing UI States into a CI Gate with unhappypath

TL;DR

What it checks

Prerequisites

Install and build from source

Reproduce the broken and good scores

Scan your application

Should `.portmap.json` be committed?

Why use `npm ci` instead of `npm install`?

Should I publish the `.env` file generated by the CLI?

Is the current `main` branch a stable release?