DEV Community: Fernando Paladini

Build a Citation-Ready Static Site with GEO Basics

Fernando Paladini — Sun, 04 Oct 2026 12:36:35 +0000

Build a Citation-Ready Static Site with GEO Basics

TL;DR

Static sites are easy to deploy, but easy to leave ambiguous. A page can look correct in a browser while missing a canonical URL, language alternates, valid structured data, a sitemap, or a clear crawler policy.

This tutorial uses GEO Basics, an MIT-licensed open-source static guide, as a small working example. You will clone the repository, serve it without a framework, run its validator, and inspect the files that make the site understandable to both people and machines.

The goal is not to manufacture rankings or force an AI system to cite a page. The goal is a crawlable, readable, source-backed site with checks that catch common publishing mistakes before deployment.

What you will build

You will run a static site locally and verify that it has:

human-readable HTML with a clear page title and headings;
canonical and hreflang links for English and Brazilian Portuguese;
JSON-LD that matches visible TechArticle and FAQPage content;
a root robots.txt, sitemap.xml, and optional llms.txt guide;
a repeatable Node.js validation command.

GEO Basics has no framework, build step, database, or runtime server in its documented workflow. The current repository also includes committed Mermaid sources and rendered SVG diagrams. There is no tagged release, so the commands below use the current main checkout. At the time of writing, the verified commit is acd0b37f041db701aa8f7edcd3e280ee4662f7db.

Prerequisites

You need:

Git;
Node.js with a current node executable;
a browser;
a terminal with network access for the clone.

The validator uses only Node.js built-ins. You do not need to install an npm package for this repository.

Clone and inspect the site

Clone the public repository and enter it:

git clone https://github.com/paladini/generative-engine-optimization-basic-guide.git
cd generative-engine-optimization-basic-guide

The repository's top-level files are intentionally understandable. index.html is the canonical English page. The Portuguese page lives at lang/pt-br/index.html. robots.txt points crawlers to the sitemap, and sitemap.xml lists both language URLs and their alternates.

The site is served as files. Start a local server from the repository root:

python -m http.server 8123 --bind 127.0.0.1

Open http://127.0.0.1:8123/ in a browser. The Python command is only a local smoke test. It is not part of the project's validator and does not deploy anything.

Understand the page signals

Open index.html and look at the <head> before changing the body. The page declares lang="en", a viewport, a descriptive <title>, a meta description, robots instructions, and a canonical URL:

<link rel="canonical" href="https://paladini.github.io/generative-engine-optimization-basic-guide/">
<link rel="alternate" hreflang="en" href="https://paladini.github.io/generative-engine-optimization-basic-guide/">
<link rel="alternate" hreflang="pt-BR" href="https://paladini.github.io/generative-engine-optimization-basic-guide/lang/pt-br/">

The canonical URL answers which URL represents the English page. The alternate links connect the language variants. They do not translate content, improve a page by themselves, or guarantee that a search engine will display a particular version. They reduce ambiguity when the same guide exists in more than one language.

The page also includes JSON-LD with a TechArticle and an FAQPage. The important rule is consistency: structured data should describe content that is visible on the page. If you add an FAQ only to JSON-LD but not to the rendered HTML, the metadata describes something a reader cannot see.

Google's current guidance says that normal SEO foundations remain relevant for its generative AI features. It also says that structured data is not required for generative AI search and that there is no special markup that guarantees visibility. Treat JSON-LD as a useful description of an already-good page, not as a shortcut.

Add crawler and agent context carefully

The repository contains a simple robots.txt:

User-agent: *
Allow: /

Sitemap: https://paladini.github.io/generative-engine-optimization-basic-guide/sitemap.xml

This permits normal crawling and advertises the sitemap. Crawler policy is an access decision, not a ranking trick. If you change it, check the rules for the user agents you actually intend to control.

The site also includes llms.txt, a human-readable Markdown map of the guide, repository, contributing instructions, sitemap, and primary references. The file is useful as a concise orientation document for tools that choose to read it. It is not a replacement for HTML, robots.txt, or sitemap.xml.

That distinction matters because the current Google documentation explicitly says Google Search ignores llms.txt for Search and that creating one neither helps nor harms Google rankings. The /llms.txt proposal itself describes it as a convention for giving agents a concise guide to important resources. Use it as an optional documentation surface, not as an access-control file or a promise of AI citations.

For OpenAI crawlers, the controls are separate. OpenAI documents OAI-SearchBot for search and GPTBot for potential training use. A site owner can make an independent policy decision for each user agent in robots.txt. Do not infer that allowing one means allowing the other.

Run the project's validator

From the repository root, run the exact documented command:

node scripts/validate-site.mjs

The current script checks that the required HTML, CSS, JavaScript, image, diagram, crawler, sitemap, and llms.txt files exist. It checks JavaScript syntax, expected PNG dimensions, internal anchors, external-link safety attributes, canonical and hreflang links, JSON-LD parsing, required schema types, and the canonical GitHub Pages URL.

The expected result for the current checkout is:

Static validation passed.

During copy edits, the repository also documents a faster command:

node scripts/validate-site.mjs --quick

The quick mode skips some diagram, image-dimension, sitemap, and robots checks. Use it for fast feedback while editing text, then run the full command before opening a pull request or publishing.

Verify a useful failure mode

A validator is more valuable when it can fail for a meaningful reason. In a temporary copy, remove a required file such as llms.txt and run the full command again. The script should report a missing required file and return a non-zero exit code. Restore the file before continuing.

Do this experiment in a disposable copy or with version control ready to restore the file. The repository's contributor guide says that changes should stay focused and that metadata, canonical URLs, language alternates, structured data, accessibility, and validation should be checked together.

The validator is deliberately local. It does not prove that GitHub Pages has deployed the latest commit, that a search engine indexed a page, or that an AI answer system will use it. Those are separate operational and external states.

Why this structure works

The site makes the primary content visible in ordinary HTML, uses descriptive section headings, links to original sources, and keeps the English and Portuguese pages connected. These choices help readers first and provide clearer inputs for crawlers and downstream tools.

The repository also keeps its validation close to the content. That is a practical design decision for a static site: a contributor can run one command without learning a framework-specific build pipeline. The checks are not a substitute for editorial review, accessibility testing, link review, or a real deployment check, but they prevent several easy-to-miss regressions.

Failure modes and security boundaries

Do not treat passing validation as proof of search performance. Google says that meeting technical requirements and best practices does not guarantee crawling, indexing, or serving. Avoid services or tools that promise an internal ranking score or guaranteed AI placement.

Do not copy a page's visible claims into JSON-LD without checking that the claims remain visible and accurate. Incorrect structured data can make a page less trustworthy and can fail eligibility for supported rich-result features.

Do not place secrets in a static repository. Static HTML, JavaScript, robots.txt, sitemaps, and llms.txt are public once deployed. Review source links, email addresses, generated assets, and build artifacts before publishing.

Finally, remember that llms.txt is not a firewall. Use hosting permissions, authentication, and robots.txt policies for the boundaries they actually support. A public page should be written as public content.

FAQ

Does GEO Basics require a framework?

No. The documented path is a static site served directly from files. The repository's validator is a Node.js script, not a framework build.

Does JSON-LD guarantee an AI citation?

No. It can describe visible page meaning, but no markup guarantees a citation, ranking, inclusion, or traffic.

Is `llms.txt` required for Google Search?

No. Google's current documentation says Google Search ignores it. It can still be maintained as an optional guide for other tools and readers.

What should I verify after deployment?

Check the deployed URLs over HTTPS, inspect the rendered HTML, fetch robots.txt and sitemap.xml, confirm the canonical host, and run the same content checks against the deployed site where possible. Then use the relevant webmaster tools to observe indexing and performance rather than assuming them.

Takeaway

GEO Basics is a compact example of a static site that treats discoverability as documentation quality: readable HTML, explicit metadata, language relationships, source links, crawler files, and a local validator. Start with the page a person should trust, add machine-readable context that matches it, and keep every guarantee out of the implementation unless you can prove it.

If you maintain a static site, which check would catch the most expensive publishing mistake in your workflow: canonical URLs, language alternates, structured data, crawler policy, or deployment verification?

AI assistance disclosure: AI assistance was used to organize this tutorial and review its wording. The repository state, validator behavior, commands, current files, license, and platform guidance were checked against the linked primary sources and the current public checkout.

Fetch Multilingual Daily Reflections in Node.js with aa-daily-reflections

Fernando Paladini — Sat, 03 Oct 2026 12:39:05 +0000

Fetch Multilingual Daily Reflections in Node.js with aa-daily-reflections

TL;DR

If you need a small Node.js integration for dated Daily Reflections from Alcoholics Anonymous, the aa-daily-reflections package provides both a JavaScript API and the aa-daily command-line tool. This tutorial uses the published npm package to fetch a date in English, Spanish, or French, then adds input validation and a responsible failure path.

The important boundary is that this package retrieves content from the public AA.org service. It is an unofficial client, not an archive or a license to republish the returned text. Use it for personal, educational, or recovery-support workflows, respect the source's terms, and avoid unnecessary requests.

What you will build

You will install the published package, query one known date from the command line, request another language, and handle an invalid date without making a network request. The same package also exposes a DailyReflections class for JavaScript and TypeScript programs.

The project is maintained in the public paladini/aa-daily-reflections-api repository and published as aa-daily-reflections on npm. At the time of writing, the npm package reports version 1.0.1, MIT licensing, Node.js >=16.0.0, npm >=8.0.0, and support for Windows, macOS, and Linux on x64 and arm64.

Prerequisites

You need:

Node.js 16 or newer and npm 8 or newer.
Network access to the upstream service when fetching a reflection.
A use case that is allowed to retrieve the source content.

The commands below use npx --yes so you can try the CLI without adding it to a project first. For a repeatable application, install it as a dependency and commit your lockfile.

Start with the CLI

Run the help command first. It is a useful smoke test because it exercises the published package and does not request reflection content.

npx --yes --package=aa-daily-reflections aa-daily --help

The CLI supports today's reflection, a date in MM/DD form, and language selection with en, es, or fr. To request June 25 in Spanish:

npx --yes --package=aa-daily-reflections aa-daily -d 06/25 -l es

The command prints display metadata such as the date, title, source reference, and reflection text. Do not copy that output into a public article, product database, or search index without checking the copyright and distribution terms that apply to the source content.

For today's English entry, the shorter form is:

npx --yes --package=aa-daily-reflections aa-daily

For a French date, use the explicit flags:

npx --yes --package=aa-daily-reflections aa-daily -d 12/24 -l fr

The package README documents English as the default language and Spanish and French as additional supported languages. The CLI also documents aa-daily MM/DD as shorthand for a dated English request.

Use the JavaScript API

The programmatic API is a better fit when you want to show metadata in your own interface, add logging, or decide whether to display the full returned fields. Create a small project and install the package:

mkdir daily-reflection-demo
cd daily-reflection-demo
npm init --yes
npm install aa-daily-reflections

Create index.js with a narrow, explicit workflow:

const { DailyReflections } = require('aa-daily-reflections');

async function main() {
  const reflections = new DailyReflections('en');
  const result = await reflections.getReflection(6, 25);

  console.log({
    date: result.date,
    title: result.title,
    reference: result.reference,
    copyright: result.copyright,
  });
}

main().catch((error) => {
  console.error(`Could not fetch the reflection: ${error.message}`);
  process.exitCode = 1;
});

Run it with:

node index.js

The package's documented DailyReflection shape includes the date, day, month, month name, title, quote, reflection, reference, and copyright fields. This example intentionally prints only metadata and the copyright field. A real recovery-support UI might show the text to an authorized user, but it should not silently turn the response into a public content mirror.

Add language and date validation

The package validates calendar dates before it fetches. For example, February 30 is rejected with an error stating that day 30 is not valid for month 2. You can make that behavior part of a reusable command instead of treating every failure as a network problem:

const { DailyReflections } = require('aa-daily-reflections');

const supportedLanguages = new Set(['en', 'es', 'fr']);

async function readReflection(language, month, day) {
  if (!supportedLanguages.has(language)) {
    throw new Error(`Unsupported language: ${language}`);
  }

  const client = new DailyReflections(language);
  return client.getReflection(month, day);
}

readReflection('es', 6, 25)
  .then(({ date, title, reference }) => console.log({ date, title, reference }))
  .catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
  });

This separation matters. An invalid date is a caller-input problem. A failed fetch may be a connectivity problem, an upstream change, rate limiting, or a service response that the parser does not understand. Keeping those cases visible makes retries safer and debugging faster.

Verify the result reproducibly

Use three checks when evaluating an integration:

Run aa-daily --help to confirm that the installed package exposes the expected CLI.
Fetch a fixed date such as 06/25 in en, es, or fr and verify that the output contains date and source metadata.
Request 02/30 and confirm that the client rejects it with a validation error.

The fixed-date check is more reproducible than “today” because the expected input does not change with the calendar. Avoid asserting that a particular title or reflection body will remain unchanged unless you have a current, authorized source snapshot and a reason to retain it.

Why the package is useful

The library keeps the integration small: a language-aware client, date-oriented methods, and a CLI that maps directly to common requests. Its documented API offers getToday(), getReflection(month, day), setLanguage(language), and getLanguage(). That gives a script enough structure to build a private daily view without embedding an unofficial scraper in every application.

The repository separates utilities, HTTP handling, parsing, types, and the main client. That organization also gives contributors clear places to inspect when the upstream HTML or API behavior changes. The current repository documents an MIT license and credits AA World Services as the source of the copyrighted content.

Failure modes and security boundaries

Do not put credentials into this client. The documented workflow reads public AA.org content and does not require an API key. Still, fetched text is external input: escape it for HTML, do not render it as trusted markup, and log only the metadata you need.

Respect rate limits. Do not call getToday() on every page render if a daily cache is enough. Add timeouts, bounded retries, and a stale-data policy in a production integration. A network error is not proof that the date is unavailable.

The client is unofficial and provides no warranty. The upstream service can change its response format, availability, or terms. The repository's own development scripts also need modernization on current Windows and TypeScript installations: the documented build script calls Unix rm -rf, and the current TypeScript configuration uses the removed moduleResolution=node10 option. The published package's CLI remains the tested path for this tutorial, but contributors should verify the source checkout separately.

FAQ

Does this package store the reflections locally?

The documented client fetches content when you request it. If you add caching, define retention and access rules yourself, and do not assume that local storage grants redistribution rights.

Can I use Portuguese?

The documented supported languages are English, Spanish, and French. Do not pass an undocumented language code and treat a fallback as correct without checking the returned language.

Is this an official AA integration?

No. The README explicitly describes the library as unofficial and asks users to respect the source, copyright, rate limits, and intended educational or recovery-support use.

Should I publish the returned text in my app?

Only after checking the permissions and terms that apply to your use case. This tutorial does not grant republishing rights.

Takeaway

aa-daily-reflections is a compact way to add dated, multilingual Daily Reflections access to a Node.js script or CLI workflow. Start with the published package, validate dates before fetching, keep retries and caching conservative, and treat the upstream text as copyrighted external content rather than application-owned data.

If you build a private or educational integration with this package, what access-control and caching rule would you add first?

AI assistance disclosure: AI assistance was used to organize this tutorial and review its wording. The commands, package metadata, repository limitations, and smoke-test behavior were checked against the linked primary sources and the published CLI.

Harness Score 1.8.0 No Longer Fails Closed-Source Repos for Missing Files

Fernando Paladini — Fri, 02 Oct 2026 23:13:49 +0000

A proprietary repository can declare its license in composer.json or package.json and still have no root LICENSE file. It can also have no MCP config. Harness Score used to score both as hygiene failures.

Harness Score 1.8.0, published on October 2, 2026, takes those checks out of the percentage when they do not apply. They stay in the report. They do not earn points for absence.

Thanks to Anderson Rogani for reporting this in issue #73.

What leaves the score

HYG-05 is not applicable when there is no root LICENSE, LICENSE.md, LICENSE.txt, or COPYING, and the root manifest license is proprietary or UNLICENSED. Composer accepts a string or an array of only those values. A nested manifest does not count. A real license file still passes.

HYG-08 is not applicable when no MCP config exists. HYG-04 can still pass, because there is nothing to leak. HYG-08 does not award points for that absence.

The JSON field is checks[].applicable: false, with passed still false and zero points earned. Those points leave the numerator and the denominator. --diff calls that became-not-applicable or became-applicable.

"private": true and Cargo publish = false are publish flags, not licenses. HYG-05 never reads Cargo.toml.

What I scanned

On October 2, 2026, npx --yes harness-score@1.8.0 scored an otherwise empty directory with "license": "proprietary" in composer.json at L0, 11/103. HYG-05 and HYG-08 were not applicable. The full catalog is still 108 points when every check applies.

"private": true alone still failed HYG-05, at 11/105. So did "license": "MIT" with no license file. Comparing the private package with the proprietary Composer sample, the CLI reported:

Score: 11/105 (10%) → 11/103 (11%) (+1pp)
Now not applicable: HYG-05

Earned hygiene points stayed at 10. The percentage rose because a failed check left the denominator.

npm view harness-score version returned 1.8.0. If you gate CI on --min-level, pin that version and compare earned points over the applicable maximum. I did not scan the private repository from the original report.

Install 36 Local Developer Tools in Cursor with DevUtils MCP

Fernando Paladini — Fri, 02 Oct 2026 12:37:02 +0000

AI coding assistants can calculate a hash, decode a JWT, format JSON, or generate a UUID. The problem is not that these operations are difficult. The problem is making the assistant use a defined tool with visible boundaries instead of guessing, switching to an unreviewed web service, or producing a plausible but incorrect result.

DevUtils MCP packages a local Model Context Protocol server for Cursor and Claude Code. The plugin currently declares version 1.0.7 and starts devutils-mcp-server through npx. The related server exposes 36 utilities for hashing, encoding, UUIDs, JWTs, JSON, network calculations, and text processing.

This tutorial installs the plugin, shows the equivalent configuration, and verifies the important security boundary: the utility call runs in a local process, while the first npx launch may download the package from npm.

TL;DR

Install DevUtils MCP from Cursor Settings or add the repository as a Claude Code plugin. If you need a manual MCP configuration, use the documented npx -y devutils-mcp-server command. Then ask your assistant to generate a UUID or validate JSON and confirm that the tool appears in the client's MCP list.

Prerequisites

You need:

Cursor with MCP support, or Claude Code with plugin support.
Node.js 18 or newer. The server package declares engines.node as >=18.
Permission to run npx and download a public npm package the first time the server starts.

The plugin and server are MIT-licensed. The plugin repository is public and non-archived, and its manifest identifies Fernando Paladini as the author.

Install the plugin

Cursor

Open Cursor Settings, choose Customize, search for DevUtils MCP, and select Install. The repository also documents the alternative Add from GitHub path with paladini/devutils-cursor-plugin.

After installation, enable the devutils MCP server under Customize > MCPs. The plugin is a distribution wrapper: its manifest describes the plugin, while mcp.json tells the client which local command to start.

Claude Code

Run the two commands documented by the repository:

/plugin marketplace add paladini/devutils-cursor-plugin
/plugin install devutils-mcp@devutils-cursor-plugin

The plugin repository is responsible for installation and documentation. The MCP server repository remains the place for the utility implementation and tool behavior.

Any MCP client

If your client supports a manually configured stdio MCP server, use this configuration from the repository's current mcp.json:

{
  "mcpServers": {
    "devutils": {
      "command": "npx",
      "args": ["-y", "devutils-mcp-server"]
    }
  }
}

The -y flag lets npx proceed without an interactive install confirmation. For a reproducible release-oriented setup, pin the package explicitly instead:

npx -y devutils-mcp-server@1.1.0

The unpinned command is the repository's current example. The pinned command targets the server's stable GitHub release v1.1.0, which is also the current npm version checked for this tutorial.

Try a useful tool call

Once the server is enabled, ask the assistant for a small operation with an inspectable result:

Use DevUtils to generate one UUID v4. Return only the UUID and the tool name.

The server README lists generate_uuid among its generator tools. You can also try:

Use DevUtils to validate this JSON and explain the error location:
{"name":"Ada","skills":["typescript",]}

Or ask for a deterministic transformation:

Use DevUtils to calculate the network, broadcast address, and host count for 10.0.0.0/24.

These prompts are deliberately narrow. They give you an easy way to distinguish an MCP tool result from an answer generated from the model's general knowledge.

Verify the local transport

You can verify that the pinned server starts and speaks MCP over standard input and output without opening Cursor. Send an MCP initialize request to the command:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0"}}}' | npx -y devutils-mcp-server@1.1.0

A successful response includes serverInfo.name set to devutils-mcp-server, serverInfo.version set to 1.1.0, and a tools capability. The server writes a short startup message to stderr and returns the JSON-RPC response on stdout. That separation matters when an MCP client parses stdout as protocol messages.

For a client-level check, open the MCP tools panel and confirm that devutils is enabled. Then run one UUID or JSON validation request and save the returned value in your terminal or test notes. Repeating the same request should let you compare the tool output with a native library or a known test vector.

Why the wrapper is useful

The plugin solves distribution rather than inventing a second utility implementation. Cursor and Claude Code users can install one named integration, while other MCP clients can use the same server configuration. The underlying server uses consistent names such as hash_sha256, json_validate, jwt_decode, and cidr_calculate, so an assistant can select a narrow operation instead of improvising a multi-step shell command.

The project README lists 36 tools in eight groups: hash, encoding, generators, JWT, formatters, converters, network, and text. The server uses stdio transport and the package metadata identifies TypeScript, Node.js, the MCP SDK, bcryptjs, nanoid, and zod as its implementation stack.

Failure modes and limitations

If the plugin does not appear, check that you installed the repository named paladini/devutils-cursor-plugin, then restart or reload the client. If the server does not start, verify node -v, run the pinned npx command directly, and inspect stderr for npm or permission errors.

The plugin does not make an MCP-incompatible client compatible. It also does not replace native libraries in application code. The server README explicitly recommends native libraries when you are writing regular programs or need extreme performance. MCP adds process and model-tool overhead in exchange for a stable tool contract that an assistant can call.

The current plugin repository has no GitHub release object even though its manifest declares version 1.0.7. Treat that manifest version as the documented plugin version, not as proof of a tagged plugin release. The related server does have stable release v1.1.0. Keep those two version surfaces separate when reporting an installation.

Security and privacy boundaries

The plugin privacy policy says that tool inputs are processed locally by the MCP server and that the author does not operate a cloud service or receive telemetry from the plugin. That is a useful boundary, but it is not a blanket security guarantee.

The first npx invocation can contact npm to download devutils-mcp-server. Review the package source, lock down the version when your workflow requires it, and use your organization's npm controls if package downloads are restricted. Also remember that your AI client still receives the prompt and may decide which tool to call. Do not paste secrets into an assistant conversation merely because the utility itself runs locally.

JWT decoding is not signature verification, and hashing is not encryption. A local tool can reduce accidental guessing, but it does not make sensitive data safe to disclose or prove that a token is trusted.

FAQ

Does the plugin send input to Fernando Paladini?

The published privacy policy says no. The tool process runs locally, while npm may be contacted to download the package on first use.

Do I need Cursor to use the server?

No. The server is intended for any MCP-compatible client. Cursor and Claude Code are the convenient plugin paths.

Should I use the plugin or manual configuration?

Use the plugin when your client supports it and you want a guided install. Use manual configuration when you need explicit control over the command and version.

Is this a replacement for application code?

No. It is an assistant-facing utility layer. Use a native library when your application needs direct calls, tests, or high throughput.

Takeaway

DevUtils MCP gives Cursor and Claude Code a small, local toolbox with a reviewable installation path. Start with the plugin, verify one narrow tool call, and pin devutils-mcp-server@1.1.0 when release reproducibility matters. The useful habit is to keep the client integration, package download, local process, and sensitive input boundaries visible.

What is the first repetitive developer utility you would rather delegate to a validated local MCP tool than ask an AI assistant to recreate?

AI assistance disclosure: This tutorial was researched and drafted with AI assistance. Repository files, package metadata, the stable server release, and the MCP initialize example were checked against primary sources before publication.

Sources

Measure an AI Coding Harness from L0 to L4 with Harness Score

Fernando Paladini — Thu, 01 Oct 2026 12:36:22 +0000

AI coding assistants can edit a repository quickly, but speed does not tell you whether the repository can catch a bad edit. A project with no instructions, tests, or CI may produce a plausible patch and still leave every important check to chance.

This tutorial shows how to measure that surrounding system with Harness Score and use a small open-source lab to improve it step by step. The result is not a quality certificate. It is a deterministic checklist of repository evidence: context files, scoped rules, skills, hooks, sensors, CI, and hygiene.

TL;DR

Create a disposable copy of the Harness Score tutorial.
Run npx --yes harness-score . and record the initial level and score.
Improve one maturity layer at a time, checking the diff after each agent task.
Treat the score as a diagnostic and gate, not as proof that the application is correct.

Prerequisites

The tutorial documents Git, Node.js 24 or newer, and an AI coding agent that can edit a local repository. GitHub CLI is optional if you want to create a private or public copy from the template. The scanner package itself declares Node.js >=18 in its npm metadata, but following the lab's Node.js 24 prerequisite keeps the exercise aligned with its current README.

No API key is required: Harness Score is designed to make zero LLM calls and zero network requests while scanning a repository.

Start with an isolated copy

The lab is a GitHub template rather than a finished application. That is intentional. You create the small Meeting Cost CLI during the first stage, so the harness improvements remain visible instead of being hidden inside an already-complete project.

Using GitHub CLI, create a private copy and clone it:

gh repo create my-harness-lab \
  --template paladini/harness-score-tutorial \
  --private \
  --clone
cd my-harness-lab

If you do not want to create a remote repository, clone the public template locally and remove its origin:

git clone https://github.com/paladini/harness-score-tutorial.git my-harness-lab
cd my-harness-lab
git remote remove origin

The template README is written in Portuguese, but the commands and paths are ordinary Git, Node.js, and Harness Score workflows. The prompts work with different coding agents. Inspect every diff yourself and do not allow an agent to commit automatically.

Establish a baseline

Run the exact current command documented by the template and the scanner project:

npx --yes harness-score --version
npx --yes harness-score .

The current published package is 1.7.5 and the current template clone is expected to start at L0, because it contains the tutorial and license but not the application harness. In a clean clone of the template, the scanner reported 17/108 and L0 - Unharnessed on October 1, 2026.

That number belongs to one commit and scanner version, not a permanent promise. The tutorial runs an unpinned command, so record the tool version beside every baseline.

For machine-readable evidence, add --json:

npx --yes harness-score . --json > baseline.json

Keep that report outside the repository if you do not want it to affect future scans. The JSON report includes the maturity level, earned points, dimensions, checks, evidence, and remediation links.

Climb the maturity ladder

Run one prompt, inspect the resulting files, execute local checks, scan the repository, and commit a checkpoint only after review.

L0 to L1: give the agent durable context

Start by creating the smallest functional Meeting Cost CLI. The application accepts participants, meeting minutes, and hourly labor cost, then calculates the total. Keep the domain calculation separate from terminal argument handling and use Node.js built-ins only.

After confirming that the command works, add a substantive root AGENTS.md. It should describe the real files, commands, domain invariants, error handling, and security boundaries. Do not add future-stage artifacts early. A long file is not automatically useful: the scanner can detect that a context file is present and substantive, but it cannot decide whether every rule is true.

Run the scan again and inspect the failed checks. The next-level message is more useful than the headline score because it tells you which dimension is blocking progress.

L1 to L2: scope guidance and protect hygiene

Move procedural guidance into artifacts that load when needed. The lab asks for a path-scoped rule, a reusable skill, and an explicit workflow. It also adds a .gitignore and a lockfile.

This separation matters. A root context file orients every session; a scoped rule applies to relevant paths; a skill packages a repeatable procedure. The hygiene checks then make local state and credentials less likely to enter a commit or an agent context.

Do not treat a passing hygiene check as proof that a repository is safe. It only means the scanner found the expected structural evidence, such as ignored environment files and no credential signatures in harness files.

L2 to L3: add sensors and CI

At this stage, add actual feedback: tests for valid and invalid calculations, a formatter, a linter, strict type checking, and a GitHub Actions workflow. The tutorial uses fixed development-tool versions for this stage and asks you to run the complete check command locally.

The important design choice is independent feedback. A README claim that tests exist is weaker than a test file that runs. A local command is weaker than a CI job that repeats the test, lint, and type checks on every push or pull request. Harness Score checks for the presence and wiring of these sensors; you still need to review whether the tests cover meaningful behavior.

L3 to L4: close the loop with hooks

The final stage adds two Cursor hooks: a gate hook that denies dangerous shell commands and a feedback hook that formats supported files after edits. The tutorial also adds tests for allowed, denied, and malformed hook payloads.

Hooks are useful because they execute at a boundary where prose can be ignored. They are not a universal security boundary. Keep scripts local, review their inputs, fail safely on malformed payloads, and retain CI as an independent check. The scanner's L4 result means the expected hook configuration and evidence were detected. It does not prove that every possible destructive command is blocked.

Finally, add a separate GitHub Actions workflow that runs npx --yes harness-score . --min-level 4 or the equivalent project action. The gate turns the maturity level into a regression check, so removing a hook or sensor becomes visible in review.

Verify each transition

Use the same small loop after every stage:

git diff --stat
npm run check
npx --yes harness-score . --json
git status --short

The first command checks scope. The second checks product behavior and sensors once they exist. The third checks harness evidence. The last catches generated files or local state that should not be committed.

If the score differs from the README's approximate table, compare the scanner version and inspect the JSON checks rather than adding decorative files to chase points.

Failure modes and honest limits

The scanner measures filesystem and configuration facts. It does not establish that the Meeting Cost CLI is commercially useful, that tests are comprehensive, that rules are correct, or that a team actually reviews pull requests. A high score means that more feedback and guardrails are present. It does not mean an agent can be trusted without human review.

The score can change when the scanner's maturity model changes. Pin a version for release gates when stable comparisons matter. Do not compare scores from different versions without recording that difference.

The tutorial itself is a template. Its prompts are guidance for an agent, not an automatic migration. Review changes, preserve the stated file boundaries, and keep credentials out of the repository. Read the Harness Score license and the tutorial license before redistributing either project.

FAQ

Does Harness Score inspect prompts or call an LLM?

No. The project describes its checks as deterministic filesystem facts and says the scanner makes zero LLM calls and zero network requests during a scan.

Do I need Cursor to complete the tutorial?

No. The README says the prompts work with different coding agents. Cursor is used for the runtime hook example because its hook format is recognized by the scanner.

Should I optimize for 108 out of 108?

No. Use the failed checks to choose controls that fit your repository. A hook that is irrelevant to your threat model may add noise, while an untested deployment script may deserve attention even if it does not change the score.

Takeaway

An AI coding harness is an engineering system around the model. Measure it from a known commit, improve one feedback layer at a time, and preserve evidence in code, tests, hooks, and CI. The useful outcome is not a magic number. It is a repository where an agent has clearer context, faster feedback, and fewer ways to make an unsafe change silently.

What is the first missing harness layer in your repository today: durable context, scoped procedures, sensors, CI, or runtime guardrails?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The repository behavior, package metadata, current version, commands, and baseline scan were checked against the linked primary sources and a clean clone on October 1, 2026.

Curate Verifiable ActiveAdmin 4 Themes with Markdown and CI

Fernando Paladini — Wed, 30 Sep 2026 12:37:23 +0000

When a Rails theme claims ActiveAdmin 4 support, the difficult part is often not finding a screenshot. It is checking whether the theme actually targets ActiveAdmin 4's Tailwind-based asset model, whether the installation commands are current, and whether the claim can be reviewed later.

This tutorial shows how to build that review workflow with activeadmin-v4-themes, an MIT-licensed directory that curates documented ActiveAdmin 4 themes. The repository stores documentation and links, not third-party theme code. You will inspect its evidence standard, add a candidate entry, and run the same kinds of local checks used by its CI.

TL;DR

Use a small Markdown repository as a compatibility index, but require evidence before adding a theme. For each candidate, record the public source URL, license, ActiveAdmin 4 version range, asset and styling requirements, installation commands, screenshots or demo, and known limitations. Then run link checking and Markdown linting before opening a pull request.

Prerequisites

You need:

Git
Node.js and npx
A public theme repository to evaluate
Enough familiarity with Rails and ActiveAdmin to understand its asset pipeline

The directory itself is not a Ruby gem and does not install ActiveAdmin. Its current main README describes a documentation workflow, and its pyproject.toml equivalent does not exist because the project has no package manifest. The repository currently has no versioned release, so the commands below target the current main documentation checked on September 30, 2026.

1. Clone the directory and inspect the standard

Start from the public repository:

git clone https://github.com/paladini/activeadmin-v4-themes.git
cd activeadmin-v4-themes

The current README defines a narrow scope: entries must have documented, verifiable ActiveAdmin 4 support. Legacy ActiveAdmin 3 and SCSS-only themes do not belong in the main list. That distinction is important because a visual match does not prove compatibility with the newer Tailwind-based interface.

Read the contributor checklist before evaluating a project:

less CONTRIBUTING.md

On Windows PowerShell, use:

Get-Content .\CONTRIBUTING.md

The contribution guide asks you to confirm public source code and an open-source license, verify the ActiveAdmin 4 version range, check the asset and styling model, and document installation, screenshots, and limitations. It also says not to copy third-party source code or screenshots into the directory.

2. Turn a compatibility claim into evidence

Before writing a README entry, inspect the theme's own primary sources. A useful evidence record answers five questions:

Where is the public source repository?
Which license covers the theme?
Which ActiveAdmin 4 version or range is named?
Does the installation path use the ActiveAdmin 4 asset and styling model?
Is there a test, demo, screenshot, or maintainer statement that supports the claim?

The repository's issue template turns those questions into required fields. Open the template in your browser or inspect it locally:

cat .github/ISSUE_TEMPLATE/new-theme.yml

The required fields include the project URL, ActiveAdmin version support, compatibility evidence, and exact installation commands. This is a practical design choice: a maintainer can review structured evidence before editing the curated list.

For example, the current entry for activeadmin-claude-theme names ActiveAdmin 4.0.0.beta22+, Tailwind CSS v4, and a Rails Engine generator. Its installation snippet is:

gem "activeadmin-claude-theme"

bundle install
rails generate activeadmin_claude_theme:install
npm run build:css

The entry also states that the application must already use ActiveAdmin 4 with Tailwind v4 assets. That limitation belongs beside the install commands because it changes whether a reader can use the theme in an existing Rails app.

3. Add a concise, reviewable entry

The directory uses ordinary Markdown rather than a custom database. A new entry should be short enough to scan but detailed enough to verify. Give it a descriptive heading, a one-sentence summary, and a small table with these fields:

Project and canonical source URL
License
ActiveAdmin version range
Styling and asset model
Rails integration method
Verification status

Follow the table with an Install heading containing the exact commands, then a Known limitations heading. For example, the current entry uses bundle install, rails generate activeadmin_claude_theme:install, and npm run build:css as separate commands rather than hiding setup in prose.

Keep the links pointed at the original project. The directory's purpose is to make compatibility easier to inspect, not to become a mirror of someone else's code.

4. Run reproducible checks before review

The contributor guide documents the local link check:

npx --yes markdown-link-check README.md

The repository's GitHub Actions workflow runs that check together with Markdown linting. You can run both locally with:

npx --yes markdown-link-check README.md
npx --yes markdownlint-cli2 "**/*.md"

On the current checkout, the link checker reported 22 successful links and the Markdown linter reported zero issues across five Markdown files. Those results are verification of the directory snapshot, not proof that every listed theme works in every Rails application.

If a link check fails, fix the source URL or remove the claim. Do not replace a dead primary source with a search result or an unrelated mirror. If the theme's ActiveAdmin 4 support cannot be demonstrated, leave it outside the curated list and explain what evidence is missing in the issue or review.

Why this works

Compatibility directories become useful when they separate discovery from certification. A reader can discover a candidate from the list, then follow the project link to inspect its own code and installation guide. The directory adds a second, reviewable layer: version claims, asset assumptions, screenshots or demos, and limitations are visible in one place.

The repository also keeps its security boundary small. Its security policy says it contains documentation and links to external projects. It does not ship third-party theme code or application credentials. That means a contribution cannot silently add a copied dependency or a secret-bearing example to the index.

Failure modes and honest limits

A screenshot looks right, but the integration is legacy

A polished screenshot does not establish ActiveAdmin 4 support. Check whether the project documents the ActiveAdmin 4 Tailwind architecture rather than only importing the classic active_admin/base SCSS stylesheet.

The version claim is too broad

Write the narrowest range supported by primary evidence. The current directory notes that ActiveAdmin 4 is still a beta series and tells readers to confirm the upstream compatibility range before production use. Treat that as a compatibility warning, not as a promise of production readiness.

The install command hides prerequisites

Commands such as rails generate may assume an existing Rails application, ActiveAdmin, CSS bundling, import maps, or a specific Node setup. Put those prerequisites in the entry instead of presenting a partial command as a complete installation.

A listed theme changes after review

The directory is a snapshot, not a live compatibility oracle. Recheck the source repository, release notes, tests, and installation guide when upgrading ActiveAdmin or choosing a theme for a real application.

FAQ

Does this repository install themes?

No. It curates documentation and links. Installation remains the responsibility of each theme's own repository.

Can an ActiveAdmin 3 theme be listed?

Not in the main ActiveAdmin 4 list unless its current documentation verifies ActiveAdmin 4 compatibility. The README explicitly excludes legacy ActiveAdmin 3 and SCSS-only themes from that scope.

Is Markdown linting enough to approve a theme?

No. Linting checks document structure. It does not prove license ownership, version compatibility, asset behavior, or security properties. Those require primary-source review.

Takeaway

A small Markdown directory can provide real engineering value when every entry has a clear evidence threshold. For ActiveAdmin themes, verify the version, asset model, installation path, and limitations first. Then keep the record concise, link to the original project, and run link and Markdown checks before review.

This article was prepared with AI assistance for research organization and drafting. Repository facts, commands, and validation results were checked against the current public project sources and a local checkout.

What evidence would you require before trusting a compatibility directory for another Rails ecosystem?

Run Private Audio Transcription Locally with EchoTranscribe

Fernando Paladini — Wed, 30 Sep 2026 02:54:54 +0000

Sending a meeting recording to a hosted transcription service is convenient, but it also creates a data-handling decision before you have even inspected the transcript. For interviews, internal meetings, research recordings, or voice notes, a local workflow can be a better starting point.

This tutorial uses EchoTranscribe, an MIT-licensed desktop application that combines a Tauri interface with a FastAPI backend and local Whisper inference. You will install the stable v0.1.1 release, transcribe one file, choose a model, export the result, and verify what “local” means in the implementation.

TL;DR

Download the installer for EchoTranscribe v0.1.1, start the application, select an audio file, choose the base model, and export TXT, SRT, or JSON. The first transcription downloads the selected model. The repository source binds its backend to 127.0.0.1, but the application is still experimental software, not a hardened production service.

Prerequisites

For the release path, you need:

Windows 10 or later, macOS, or a Linux distribution supported by the published package.
Enough disk space for the application and a Whisper model. The README lists approximate model sizes from 39 MB for tiny to 769 MB for medium.
An audio file in MP3, WAV, FLAC, M4A, OGG, or WebM format.
Internet access for the first model download. Later runs can reuse a model already stored locally.

The project publishes an MSI and an EXE installer for Windows, DMG files for macOS, and AppImage, DEB, and RPM packages for Linux in the v0.1.1 release assets. Pick the asset that matches your operating system and CPU architecture.

If you want to run from source instead, the stable README lists Node.js 18 or later, Python 3.8 or later, Rust, and platform-specific Tauri prerequisites. That is a development path, not a requirement for using a release installer.

Install the stable release

Open the v0.1.1 release page.
Download the installer for your platform.
Install and launch EchoTranscribe.
If your platform asks for permission to open an application downloaded from the internet, confirm that you obtained the file from the project's GitHub release page.

The release page is important here because the repository's default branch can change independently of the last packaged release. The commands and behavior in this article target v0.1.1, which is the published stable release inspected for this tutorial.

Transcribe a file

The interface is intentionally small. Use this sequence:

Select one or more audio files. The README documents a maximum of 10 files in one batch.
Choose a model.
Leave automatic language detection enabled unless you know the language and want to select it explicitly.
Start transcription.
Review the text and timestamps.
Export the result as TXT, SRT, or JSON.

For a first run, start with tiny or base. The project describes tiny as faster with lower precision and base as a balance between speed and precision. small and medium may improve recognition for some material but require more resources and take longer. These are model tradeoffs, not guarantees for every recording.

The first run may take longer because EchoTranscribe downloads the chosen model. The source stores models under .echo-transcribe/models in the user's home directory. The README documents the corresponding Windows location as %USERPROFILE%\\.echo-transcribe\\models\.

Expected result

After processing, you should see the transcription in the application, with word-level timestamps when the backend returns them. An export should contain the selected format's text or timing data. The exact recognition quality depends on the recording, language, model, noise, and speaker overlap, so inspect the output before treating it as a source of truth.

Verify the local backend

The desktop interface starts a Python backend. The stable source exposes a health endpoint and API documentation while the backend is running. If you are developing from a checkout, start the backend from the repository's backend directory:

cd src-tauri/backend
python main.py

The source searches for an available port starting at 8000 and reports the selected URL in its logs. When it starts on the default port, verify the service with:

Invoke-RestMethod http://127.0.0.1:8000/health

You should receive a JSON response whose status is healthy. The API documentation is available at http://127.0.0.1:8000/docs when that port is selected. The backend code binds its port search to the loopback address, and its CORS configuration names the local frontend origins. That is useful evidence about the intended boundary, but it is not a security certification.

Run from source when you need development mode

Clone the exact stable tag instead of silently using an unreleased default branch:

git clone --branch v0.1.1 --depth 1 https://github.com/paladini/echo-transcribe.git
cd echo-transcribe
npm ci

The frontend scripts are documented in the stable package.json:

npm run dev
npm run tauri dev

In practice, treat this as a development workflow. I verified npm ci and Python bytecode compilation on the v0.1.1 checkout. The frontend build did not complete with Node.js 24 and the dependency range resolved by the lockfile because the installed TypeScript reports that the configured baseUrl option has been removed. That is a reproducible toolchain limitation, not evidence that the packaged release is unusable. Use the published installer for the shortest path, or pin and test a compatible development toolchain before changing the project configuration.

What stays local, and what does not

The repository's architecture supports a local processing workflow: the application sends files to its local FastAPI backend, and the backend uses faster-whisper to load models and transcribe them. The source writes temporary files under .echo-transcribe/temp and removes them after processing or shutdown.

There are still important boundaries:

The first model download needs network access. Local inference does not mean the initial model acquisition is offline.
A local HTTP service is not automatically safe to expose beyond the host. Do not forward its port, bind it to a public interface, or place it behind a proxy without adding authentication, transport security, input limits, and a review of the API.
Audio files and generated transcripts may remain in application, download, temporary, or operating-system locations depending on the workflow. Review and delete them according to your retention policy.
The project accepts multiple file formats, but malformed or unusual media can still fail. Keep the original recording and verify important transcripts manually.
EchoTranscribe is MIT licensed, but the license does not provide a guarantee of accuracy, availability, compliance, or fitness for a particular workload.

These constraints are why “runs locally” is a useful architectural description, not a complete threat model.

Troubleshooting checklist

The application cannot load the backend

Check whether the backend is running and whether the selected port is already occupied. The README specifically points to the local API and recommends checking port 8000. Starting the backend manually can reveal missing Python dependencies or a port selection in the logs.

The model cannot be found

Allow the first model download to finish and check your network connection. If you moved or removed the user's .echo-transcribe/models directory, the application may need to download the model again.

The result is poor

Try a larger model, reduce background noise, check the selected language, and review timestamps around speaker changes. Larger models use more resources and are not guaranteed to fix every recording.

The frontend build fails

Separate packaged use from source development. Confirm the checkout is v0.1.1, inspect the installed Node.js and TypeScript versions, and reproduce the error before changing tsconfig.json or dependency ranges. Do not claim a successful build when only the backend compiled.

FAQ

Does EchoTranscribe send audio to a cloud API?

The documented design uses local Whisper inference through its Python backend. The first model download still uses the network, and the source should be reviewed before making stronger privacy claims for a specific deployment.

Can I process several files?

Yes. The README documents batch transcription with up to 10 files per request, subject to available CPU, memory, and model resources.

Which model should I choose?

Start with base for a general test. Use tiny when iteration speed matters, then compare a larger model on a representative recording if the text needs improvement.

Is this a production transcription service?

No conclusion like that follows from the README or a local smoke test. Treat it as a self-hosted open-source desktop application and evaluate reliability, resource use, data retention, and security for your own context.

Takeaway

EchoTranscribe gives you a practical local transcription path: install a tagged release, keep model downloads explicit, process audio on the same computer, and export a reviewable result. The strongest habit is to verify the boundary yourself: inspect the release, check the loopback backend, and keep the development build limitations separate from the packaged application.

This article was prepared with AI assistance for research organization, drafting, and checklist review. The repository, release metadata, source examples, and local validation results were checked against the linked primary sources.

What would you verify first before trusting a local transcription workflow with sensitive recordings: the model files, the network boundary, or the retention behavior of exported transcripts?

Build and Test an AI Agent Skill with SKILL.md and Python

Fernando Paladini — Sat, 19 Sep 2026 12:37:02 +0000

AI agents are good at interpreting intent, but they are not a reliable place to hide every rule in a workflow. If an agent must count characters, parse a file, or refuse to overwrite an existing artifact, prose instructions alone make the result harder to verify.

An Agent Skill gives that workflow a reusable home. The skill describes when it should activate and how the agent should reason. Small scripts handle repeatable checks. Tests protect the behavior when the skill changes.

This tutorial builds a small commit-crafter skill from the public how-to-create-a-skill-tutorial repository. The project is MIT licensed and documents the open Agent Skills specification. The repository's stable documentation describes the same folder structure and examples used here.

TL;DR

Create a folder with a SKILL.md, put deterministic validation in scripts/, keep long references in references/, and test the script independently. The model chooses and explains; the script verifies and computes.

Prerequisites

You need:

Python 3.9 or newer
An agent that discovers skills from a supported skills directory
A Git repository with staged changes if you want to try the commit workflow

The example repository tests its skills with Python's standard library. You do not need an API key, a hosted model, or a third-party Python package for the minimal path.

1. Create the skill structure

The specification requires SKILL.md. The other directories are conventions that keep a skill maintainable:

commit-crafter/
|-- SKILL.md
|-- scripts/
|   `-- check_message.py
`-- references/
    `-- conventional-commits.md

Create a project-local skill directory on macOS or Linux:

mkdir -p .agents/skills/commit-crafter/scripts
mkdir -p .agents/skills/commit-crafter/references

On Windows PowerShell, use the equivalent commands:

New-Item -ItemType Directory -Force .agents\skills\commit-crafter\scripts
New-Item -ItemType Directory -Force .agents\skills\commit-crafter\references

The project-local location is useful when the skill belongs to one repository. A user-level location such as ~/.agents/skills/commit-crafter is better when you want the same skill available across projects. Check your agent's discovery rules before installing it globally.

2. Write a triggerable SKILL.md

The front matter is not decoration. The agent may read only the description while deciding whether to activate the skill, so describe both the job and the phrases that should trigger it.

---
name: commit-crafter
description: Write git commit messages from staged changes following Conventional Commits. Use when the user asks to commit, asks for a commit message, wants to fix or improve a commit message, or mentions conventional commits.
license: MIT
compatibility: Requires git and Python 3.9+
---

# Commit Crafter

Write a Conventional Commit message from the staged diff. The user reviews
and approves the message before anything is committed.

## Workflow

1. Run `git status` and `git diff --staged`.
2. Classify the change and whether it is breaking.
3. Draft the message in the format `type(scope): imperative summary`.
4. Validate it with `python scripts/check_message.py --file message.txt`.
5. Show the result. Commit only after explicit approval.

## Rules

- Never stage files yourself.
- Never commit secrets or unrelated files.
- Never add an AI attribution footer unless requested.

Notice the boundary around git commit. The skill can prepare and validate a message without silently changing repository history. That is a better default for an agent workflow that may be invoked from an ambiguous prompt.

The name must match the parent directory and use lowercase letters, numbers, and single hyphens. Keep the body short enough to load comfortably. Move detailed rules and examples into references/ and link to them one level deep.

3. Move stable rules into a deterministic script

The tutorial's central design rule is simple: let the model decide, let the script verify, and let the script crunch. A model can choose whether a change is a feature or a fix. A Python script can enforce the subject format every time.

The repository's check_message.py validates the Conventional Commits shape, allowed types, subject length, imperative mood warnings, blank-line separation, and breaking-change footers. It uses exit codes as a protocol:

0 means the input is valid
1 means validation found a rule violation
2 means there was no input

Run it against a candidate message:

python scripts/check_message.py --file message.txt

The script prints actionable violations to stderr. For example, it can report that a subject is too long or that a breaking marker lacks a BREAKING CHANGE: footer. The agent can read that output, revise the draft, and run the same check again.

That feedback loop is more robust than adding another paragraph of instructions. It also makes the rule testable without an agent in the loop.

4. Test the script before installing the skill

The example skill includes tests beside the script. Run them from the repository root:

python examples/commit-crafter/tests/test_check_message.py

The public repository's current test run completed successfully for the example suites. The commit-crafter suite covers valid messages, unknown types, subject limits, breaking changes, body formatting, and warning behavior.

Add a regression test whenever a real prompt exposes a failure. A useful test is not a copy of one successful output. It is a small input that would have caused the agent to make the wrong decision before the fix.

5. Try the skill with realistic prompts

Trigger quality is part of the implementation. Test both positive and negative cases:

"commit this"                      -> should trigger
"write a good commit message"      -> should trigger
"reword my last commit"            -> should trigger
"what does the staged diff do?"     -> should not trigger
"create a git branch"               -> should not trigger

If the skill fails to activate, improve the description with the user's vocabulary. If it activates for unrelated requests, narrow the wording. This is a practical evaluation of the trigger, not a promise that every agent implements discovery identically.

When the skill does activate, inspect whether it follows the important boundaries: it should inspect staged changes, never stage files on its own, run the validator, and wait for approval before committing.

Why this structure works

SKILL.md is the workflow contract. scripts/ is the deterministic execution layer. references/ is progressive disclosure for material that would make the main instructions noisy. assets/ can hold templates or fixtures when a skill needs them.

This separation also helps with token use. The agent does not need to reconstruct a parser from prose or load every example before starting. It can read the short workflow, run a local script, and consult a reference only when the situation requires it.

The repository extends the same pattern with changelog-forge, lessons-keeper, and skill-starter. Those examples demonstrate deterministic Git parsing, idempotent memory writes, and a copy-paste scaffold.

Failure modes and security boundaries

A skill is executable code with the permissions of the agent. Read scripts before installing a third-party skill. Treat network calls, credential access, shell pipelines, and automatic writes as explicit capabilities that need a reason and a documented boundary.

Common problems include:

A vague description that never triggers, or triggers for unrelated requests.
Instructions that claim a validation rule but have no executable check.
A script that appends repeatedly when retried instead of being idempotent.
Unix-only path assumptions in a skill advertised for Windows.
A skill that commits, publishes, or reads secrets without an explicit user decision.

The tutorial's examples prefer Python's standard library, bounded output, explicit exit codes, and local execution. These choices reduce dependencies, but they do not make an arbitrary skill automatically safe. Review the code and its compatibility requirements before installation.

FAQ

Is a skill the same as an MCP server?

No. A skill is an instruction and resource bundle discovered by an agent. MCP is a protocol for exposing tools and data. A skill can tell an agent when to use an MCP tool, but the two solve different problems.

Should every skill include a script?

No. Use a script when a stable rule benefits from exact, repeatable behavior. A small explanatory workflow may only need SKILL.md and a reference file.

Can the skill guarantee the agent will follow it?

No. It can improve activation, make important rules explicit, and provide executable checks. The host agent still controls discovery and execution.

Where should I install it?

Use a project-local .agents/skills/ path for repository-specific behavior. Use a user-level path only after reviewing the skill and confirming how your agent discovers global skills.

Takeaway

An effective Agent Skill is a small, reviewable software project: a precise trigger, a short workflow, deterministic scripts, references loaded on demand, and tests that reproduce failures. Start with one narrow task such as commit-message drafting, then add automation only where the boundary and verification are clear.

What is one repetitive agent workflow in your project that would benefit from a deterministic check before the agent is allowed to continue?

AI assistance disclosure: This tutorial was researched and drafted with AI assistance. Repository behavior, commands, version information, license, and test claims were checked against the public project sources before publication.

Publish a Ghost Blog on GitHub Pages with the v3 Release

Fernando Paladini — Fri, 18 Sep 2026 12:35:17 +0000

Ghost is a pleasant writing environment, but running a dynamic CMS and paying for hosting is more than every personal blog needs. The ghost-on-github-pages project takes a different route: write in a local Ghost installation, generate static files, and push those files to a public GitHub repository served by GitHub Pages.

This tutorial follows the project's stable v3.0.0 release. It covers the smallest useful path from an empty machine to a published static blog, then explains what the scripts actually do and where their boundaries are.

TL;DR

On macOS, Linux, or WSL, install Node.js LTS and wget, download the v3.0.0 release, and run:

chmod +x install.sh
./install.sh

The installer creates ~/.ghost, installs Ghost locally, starts it on port 2373, and optionally asks whether to publish immediately. After creating a post in Ghost Admin, publish changes with:

cd ~/.ghost
./deploy.sh

The result is a static site at https://USERNAME.github.io/REPOSITORY.

Prerequisites

The project's v3 requirements are deliberately small:

macOS or Linux. Windows users can use WSL.
Node.js LTS, documented for v18 or v20.
wget.
Git and a GitHub account.
A public GitHub repository for the generated site.

You do not need Python for v3. The project replaced its Classic v2 Python-based publishing tool with gssg, a Node-based static-site generator. The exact Ghost and gssg versions are installed by the release scripts, so do not assume that a globally installed copy is equivalent to this workflow.

Check the prerequisites in a Unix-like terminal:

node --version
wget --version
git --version

Install Ghost locally

Download and extract the v3.0.0 archive, then enter the extracted directory. The release's install.sh checks for node, npm, and wget, creates ~/.ghost, installs ghost-cli@latest, and runs a local Ghost installation on port 2373.

Run it like this:

cd path/to/ghost-on-github-pages
chmod +x install.sh
./install.sh

The script may take several minutes because it downloads and configures Ghost. When it finishes, open:

http://localhost:2373/ghost

Create the administrator account, then make a small test post. The local editor is the source of truth for writing. The GitHub repository will contain the generated public output, not your local Ghost database or administrator interface.

If you want to postpone the first publish, use the documented option:

./install.sh --skip-deploy

That flag is useful when you want to finish local configuration before creating or selecting a GitHub destination.

Publish the static site

When the blog is ready, run the release's deploy script from the Ghost folder:

cd ~/.ghost
./deploy.sh

On the first run, the script asks for your GitHub username, repository name, and repository URL. It stores those settings in ~/.ghost/deploy.conf. For a project site named my-blog, the expected public URL is:

https://USERNAME.github.io/my-blog

For a user site named USERNAME.github.io, GitHub Pages uses the root URL instead.

The script first makes sure Ghost is running and sets the local site URL to http://localhost:2373. It then runs gssg, copies the project's small index.html wrapper when present, validates the generated static directory, and pushes the publish directory to the master and gh-pages branches. The repository's deployment guide documents the same lifecycle.

After the push, allow GitHub Pages time to build and serve the site. The project documentation says to wait about ten minutes, but the actual delay depends on GitHub's current Pages processing.

Verify the important failure boundary

Do not stop at a successful git push. Verify both the local generated files and the public URL:

cd ~/.ghost
./scripts/validate-static.sh static

The validator fails if generated files contain localhost:2368 or localhost:2373, or if they contain the known malformed JPEG suffixes .jpegg, .jpegpg, or .jpegjpg. The repository includes fixtures for both failure cases. Its validation test suite can be run from a checkout of the release:

./tests/run-validation-tests.sh

Then open https://USERNAME.github.io/REPOSITORY in a browser and check the home page, one post, one tag, and one image. A static site can look healthy on its home page while a post link or asset still points at localhost, so those deeper checks matter.

Why this works

The architecture is a simple publishing pipeline:

Ghost provides the local editing and administration experience.
gssg turns the local Ghost site into static HTML, CSS, JavaScript, and assets.
The validator checks for two classes of broken output.
Git pushes the generated directory to GitHub Pages branches.

That separation gives you a rich editor without exposing Ghost Admin to the public internet. It also makes the hosted result cheap and easy to inspect: the public repository contains the files visitors receive.

Limitations and security boundaries

This is a local publishing workflow, not a hosted Ghost service. You are responsible for keeping the local Ghost installation, Node.js, Git credentials, and administrator account secure. The public Pages repository should contain generated site output only. Never commit .env files, database exports, admin credentials, access tokens, or private drafts.

The deploy script uses force pushes for its master and gh-pages targets. That matches the project's intended publishing model, but it can overwrite history on those branches. Use a dedicated site repository, confirm the remote URL before the first publish, and do not point the script at a repository containing unrelated work.

The project documents macOS, Linux, and WSL, with Node.js 18 or 20 as the supported examples. Native Windows PowerShell is not the documented environment because the workflow depends on Bash commands and Unix tools. The repository's scripts also expect network access to install Ghost and generate the static site.

If the site still contains localhost links, consult the troubleshooting guide. If you are upgrading the old Classic v2 workflow, use the project's migration guide instead of copying v3 files into an existing Ghost folder.

FAQ

Is Ghost running publicly?

No. Ghost runs locally at http://localhost:2373. GitHub Pages serves the generated static output.

Do I need Python?

Not for v3. Python was part of the Classic v2 path.

Can I publish updates?

Yes. Start Ghost, edit or publish the post locally, then run cd ~/.ghost && ./deploy.sh again.

What happens if there are no changes?

The deploy script reports that there are no changes to publish. Make sure the post was saved or published in Ghost before trying again.

Takeaway

The useful idea is not merely hosting a blog for free. It is separating writing from delivery: Ghost handles local authoring, while gssg, the validator, and GitHub Pages handle a reviewable static artifact. Start with the v3.0.0 release, publish a test post, and verify a post, tag, and image before treating the site as ready.

Have you used a local CMS with a static publishing target? I would be interested in which part of the workflow you would automate next: preview builds, link checking, or branch protection.

AI assistance disclosure

AI assistance was used to organize this tutorial and improve wording. The commands, version references, workflow behavior, limitations, and validation claims were checked against the v3.0.0 release, its documentation, scripts, and fixture tests before publication.

Translate Git Commit Messages Offline with Python and Argos Translate

Fernando Paladini — Thu, 17 Sep 2026 12:37:32 +0000

TL;DR

Mixed-language commit histories make changelogs, release notes, and repository archaeology harder to scan. git-translate-commits is a Python CLI that translates commit messages to a target language. Its default engine is local Argos Translate, so the documented offline path does not require an API key.

This tutorial uses the stable v1.0.1 release to build a cautious workflow: install the tool in an isolated environment, preview the changes, restrict the commit range when useful, and only then decide whether rewriting history is appropriate.

Prerequisites

You need:

Python 3.10 or newer.
Git installed and available on your PATH.
A local clone of a repository whose history you are allowed to rewrite.
pipx, uv, or another isolated Python installation method.

The project is released under GPL-3.0-or-later. The commands below target the published 1.0.1 package and the matching Git tag, not an unreleased default-branch change.

Install the CLI in isolation

The project README recommends pipx or uv for CLI installation. pipx keeps the application's dependencies out of the rest of your Python environment:

pipx install git-translate-commits==1.0.1

You can verify the installed version without touching a repository:

git-translate-commits --version

The package metadata declares the console entry point git-translate-commits and requires Python 3.10 or newer. The default dependencies include Argos Translate, GitPython, language detection, Rich, and python-dotenv.

Preview a translation without rewriting history

Change into a disposable clone or a repository where you have permission to work. Start with the documented dry-run command:

cd path/to/your-repository
git-translate-commits --lang en --dry-run

The --lang option is required. The --engine option defaults to local, and --dry-run reports what would change without applying a rewrite. The local engine may download a language pack on first use. After that initial download, translation is designed to run offline.

If your current branch contains only English messages, a dry run may report that there is nothing to do. That is still a useful result: it confirms the repository can be read and that the selected language detector does not identify work unnecessarily.

For a more controlled preview, narrow the input. For example, this checks commits after a date and only for one author:

git-translate-commits \
  --lang en \
  --since "2025-01-01" \
  --author "dev@example.com" \
  --dry-run

The CLI also supports --until, repeatable --branch, and --all-branches. These filters are useful when you are cleaning a recent slice of history rather than attempting to process every ref.

Choose the local engine deliberately

The local engine is the safest starting point for a repository containing unpublished work. It uses Argos Translate instead of sending messages to an external API:

git-translate-commits --lang pt-BR --engine local --dry-run

That does not mean the tool has no external activity ever. Argos language packs are downloaded automatically when first needed, and the package itself comes from the Python package index during installation. Once the required language data is available, the documented local translation path is intended to operate without an API key.

The project also provides an optional LLM engine through the llm extra. It supports OpenAI, Anthropic, and OpenAI-compatible providers through LiteLLM:

pipx install "git-translate-commits[llm]==1.0.1"
git-translate-commits --lang en --engine llm --provider openai --model gpt-4o-mini --dry-run

Use the LLM path only when its data handling and cost are acceptable for your commit history. The README documents OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables. Never place a real key directly in a committed script or shared shell history.

Apply a rewrite only after review

If the dry-run report is correct and the repository is ready for a history rewrite, run the same selection without --dry-run:

git-translate-commits --lang en --engine local

The default behavior creates a backup branch before rewriting. You can inspect the available safety controls with:

git-translate-commits --help

The CLI exposes --backup/--no-backup, --force, and --preserve-conventional/--no-preserve-conventional. The default preserves Conventional Commit prefixes such as feat: and fix:. The project also documents a JSON log containing the original and translated mapping.

For a shared repository, coordinate before force-pushing. Commit messages are part of Git commit objects, so changing them changes commit hashes. Existing branches, open pull requests, signed commits, release references, and downstream clones may need attention after the rewrite.

Verify the result

After a real rewrite, inspect the backup branch and compare the history before considering any push:

git branch --list "backup/pre-rewrite-*"
git log --oneline --decorate -n 20
git diff --stat "backup/pre-rewrite-*" HEAD

The exact backup branch name includes a timestamp, so replace the wildcard with the name printed by the tool when running commands that require one exact ref. Also inspect the generated .git-translate-log.json file if the run produced it. It provides a reviewable mapping instead of requiring you to infer every change from the new hashes.

If the result is wrong, stop before pushing. The backup branch is the recovery point documented by the project. A local history rewrite is reversible only while you still have an intact reference to the old commits.

Why this workflow works

There are three separate decisions here. First, language selection determines the intended output. Second, the engine determines whether messages remain local or are sent through an LLM provider. Third, the rewrite step changes immutable Git history. Keeping those decisions separate makes the process easier to review.

The tool also preserves more than a one-line subject. The README says it preserves file contents, author and committer metadata, timestamps, Conventional Commit prefixes, issue references, and Git trailers such as Signed-off-by. Translation changes the message text, but it is not intended to rewrite the files in each commit.

The v1.0.1 checkout includes a test suite. I ran it from a clean checkout with the source package available on PYTHONPATH: all 43 tests passed. That verifies the checked-out package behavior, but it is not a guarantee that every repository or language pair will produce a good translation.

Failure modes and honest limits

The history is not clean

The pipeline refuses to rewrite a repository with uncommitted changes unless it is running in dry-run mode. Commit or stash changes first, or use a disposable clone.

A language pack is unavailable

The local engine may need to download a language pack. Plan for that first-run network step, and verify that the requested language pair is supported before a large run.

Translation quality is not uniform

Commit messages contain abbreviations, product names, issue identifiers, code symbols, and project-specific vocabulary. Review the dry-run output. The local engine is useful for normalization, not a substitute for a human review of important release history.

Rewriting can disrupt collaborators

Changing commit messages changes hashes. Do not force-push a shared branch casually, and remember that a backup branch on your machine does not automatically protect every remote clone.

LLM mode changes the privacy boundary

The optional LLM engine can send commit content to the configured provider. Use local mode when messages may contain confidential names, incident details, customer references, or unreleased plans.

FAQ

Does the default mode require an API key?

No. The documented default is the local Argos Translate engine. It may download language data on first use, but it does not require an LLM API key.

Can I translate only one branch or author?

Yes. Use --branch, --author, --since, and --until to constrain the selection. Use --all-branches when you intentionally want all local branches processed.

Does it change source files?

The project documents preservation of file contents. The operation rewrites commit messages and therefore commit hashes, not the snapshots represented by those commits.

Should I use this on a public repository?

Only with a reviewed migration plan. A public history rewrite can break links, signatures, forks, pull requests, and consumers that refer to old hashes.

Takeaway

git-translate-commits is most useful when language consistency is worth a controlled history migration. Start with v1.0.1, use the local engine, preview with --dry-run, keep the automatic backup, and review the log before changing a shared ref.

Have you ever normalized a mixed-language Git history, and which preservation rule mattered most in your repository?

AI assistance disclosure

AI assistance was used to help organize and edit this tutorial. The commands, version details, license, documented behavior, and test result were checked against the public v1.0.1 source, README, package metadata, and a clean checkout of the project.

Add a Research-Backed Timeline Event with Astro and YAML

Fernando Paladini — Wed, 16 Sep 2026 12:37:48 +0000

TL;DR

An interactive timeline is only as useful as the evidence behind each event. In this tutorial, you will add a new milestone to The History of AI-Assisted Development, a public MIT-licensed Astro site. The workflow is deliberately small: edit one YAML collection, attach a primary source, run the repository's build checks, and inspect the generated page.

The same pattern works for release histories, standards timelines, migration guides, and other documentation sites where the data should remain easy to review.

Prerequisites

You need:

Node.js installed on your machine
pnpm 9.15.0, matching the repository's packageManager field
Git
A primary source for the milestone you want to document

The repository currently declares version 1.0.0 and uses Astro 5, React 19, Tailwind CSS 4, Mermaid 11, and TypeScript 5. The exact dependency versions are resolved by pnpm-lock.yaml, so use the lockfile when installing.

Clone the project and install its locked dependencies:

git clone https://github.com/paladini/history-of-ai-assisted-development.git
cd history-of-ai-assisted-development
pnpm install --frozen-lockfile

Find the timeline data

The repository keeps timeline events in content/timeline/events.yaml. The rendering code consumes this collection and turns the records into the interactive timeline. You do not need to edit an Astro component for a normal event.

The project also documents the content contract in CONTENT_GUIDE.md. Every event requires a unique identifier, an ISO date, one of the supported era IDs, a title, a two or three sentence summary, a category, and at least one Tier 1 source.

The source policy is important. A primary announcement, official repository, or authoritative survey is stronger than a secondary article repeating the same claim. If you only have an approximate date, use the first day of the month and say that the date is approximate in the summary.

Add one event

Open content/timeline/events.yaml and add a record with the existing indentation style. Here is a complete example for an event that can be verified against the official Model Context Protocol repository. The date and era are part of the site's content model, while the source URL gives a reader a path to the underlying evidence.

- id: mcp-open-source-release
  date: 2024-11-25
  era: protocols-standards
  title: "Model Context Protocol is released as an open standard"
  summary: "Anthropic publishes the Model Context Protocol as an open standard for connecting AI applications to external tools and data sources. The release gives developers a documented protocol boundary instead of relying only on provider-specific integrations."
  category: protocol
  sources:
    - label: "Model Context Protocol repository"
      url: "https://github.com/modelcontextprotocol"

Before saving, check each field:

id is unique and uses lowercase kebab case.
date uses YYYY-MM-DD.
era exactly matches one of the six IDs in the content guide.
category is one of tool, protocol, concept, culture, or data.
summary explains what happened without claiming more than the source supports.
sources contains at least one usable URL.

The example is a data change, not an invitation to copy a historical claim blindly. Read the linked source yourself and adjust the wording if its scope, date, or terminology differs.

Validate the result locally

The repository provides a verification script that installs dependencies, runs the build, and checks that the static output exists. Run it after editing the YAML:

pnpm build:verify

For a direct production build, run:

pnpm build

The build should finish successfully and generate the static site in dist/. The project currently builds the home page, about page, data page, and glossary routes. The timeline is part of the home page, so a successful build confirms that the collection was parsed and the page was generated.

To inspect the result in a local browser, start Astro's development server:

pnpm dev

Then open the local URL printed by Astro. Use the timeline controls to locate the new event and verify the visible title, date, era, summary, category, and source link.

Why this workflow works

The data and presentation have separate responsibilities. YAML makes the historical record readable in a pull request, while Astro components handle layout and interaction. That separation keeps a content correction small and reduces the chance of breaking the interface while adding research.

The source list also makes review concrete. A reviewer can check whether the event date is supported, whether the summary distinguishes a protocol from a product, and whether the chosen era is reasonable. A link is not proof by itself, but a visible source gives the reviewer something specific to evaluate.

The locked install matters too. pnpm install --frozen-lockfile prevents the local dependency graph from silently changing while you validate the content. This is especially useful for a static site with several client-side visualization packages, because a content edit should be tested against the same dependency resolution used by the repository.

Common failure modes

The build reports malformed YAML

Check indentation, quoting, and list markers. YAML treats indentation as structure. A missing space after - or an inconsistent nesting level can prevent the content collection from loading.

The event does not appear

Confirm that the record is in content/timeline/events.yaml, not a similarly named file. Check that its era value exactly matches the documented IDs and that the date is a valid ISO date. Then restart the development server if its content watcher did not reload the file.

The source is weak or ambiguous

Replace a search result or commentary article with the original announcement, official repository, specification, or survey. If the original source does not establish the exact date, make the date approximate and say so. Do not fill gaps with confident prose.

The page builds but the claim is still wrong

Build validation checks structure and rendering. It does not fact-check dates, assess source quality, or detect a misleading summary. Historical review remains a human responsibility, supported by the source policy and pull request discussion.

Limitations and security boundaries

This workflow produces a static site. It does not create a database, authenticate users, or fetch remote sources during the build. The source links are references for readers; they are not automatically verified by the repository's build command.

The example uses public URLs and contains no credentials. Keep tokens, private research notes, and unpublished material out of events.yaml and the repository. A public timeline should describe public evidence only. Review external links before merging because a link can lead to content that changes after the event is recorded.

FAQ

Do I need to know Astro?

No. For a normal milestone, the documented YAML record is enough. Astro knowledge becomes useful when changing the timeline layout, adding filters, or modifying the generated pages.

Can an event have multiple sources?

Yes. Add more entries under sources when independent primary sources clarify different parts of the claim. Keep the summary concise and make each source relevant.

Does `pnpm build` verify links?

It verifies the site's build, but you should not treat that as proof that every external URL is reachable or authoritative. Check important links separately during review.

Can I add a new era?

Not through an event record alone. Era IDs are part of the site's model and the content guide. A new era may require coordinated changes to data, types, and presentation, so open a focused change that documents the design decision.

Takeaway

A research-backed timeline entry can be a small, reviewable change: one YAML record, one or more primary sources, and a reproducible build. The valuable habit is not merely knowing the syntax. It is preserving the chain from a historical claim to evidence that another person can inspect.

What is the most useful validation you would add next: automated link checks, a schema-level date validator, or a review report for events missing Tier 1 sources?

AI assistance disclosure

AI assistance was used to help organize and edit this tutorial. The repository documentation, current package metadata, source policy, and build commands were checked against the public project before publication. The historical example should still be reviewed against its linked primary source.

Block Accidental AI Credit in Git with a Local Go Hook

Fernando Paladini — Tue, 15 Sep 2026 12:38:56 +0000

AI coding tools can leave a small but consequential trace in a commit message or pull request: a generated-by footer or an automatic Co-authored-by trailer. If that text does not belong in your project's public history, discovering it in CI is already too late.

This tutorial shows how to add a local, deterministic guardrail with ai-credit-scrub. The tool is a Go CLI that works offline for cleaning and checking text. It can rewrite the temporary commit message, reject an escaped credit before a push, and sanitize pull request text before delegating to your existing GitHub CLI authentication.

The goal is narrow: remove explicit AI-agent credit lines when your policy requires it, while preserving ordinary human attribution and product mentions.

TL;DR

Install the released CLI, run ai-credit-scrub install --git inside a repository, and test it with a message containing an explicit credit. The commit-msg hook rewrites the message before Git creates the commit, while pre-push checks outgoing commit messages. For pull requests, use ai-credit-scrub pr create instead of calling gh pr create directly.

Prerequisites

You need:

Git installed and a local repository where you can install hooks.
Go 1.26 or a prebuilt binary from the project's release page.
The stable v1.1.0 release used in this tutorial.
GitHub CLI only if you want the pull request wrapper. It must already be authenticated locally.

The repository is public, MIT licensed, non-archived, and owned by Fernando Paladini. The release source declares Go 1.26.0 in go.mod.

Install the released CLI

The documented Go installation command is:

go install github.com/paladini/ai-credit-scrub/cmd/ai-credit-scrub@v1.1.0

Check that the executable is available:

ai-credit-scrub --help

The current CLI exposes five relevant entry points: clean, scan, check, install, and pr create. clean rewrites text, scan reports matches, and check is the non-rewriting check used by the push hook.

Install the Git boundary

From the repository you want to protect, run:

ai-credit-scrub install --git

The installer adds two chained hooks:

commit-msg receives Git's temporary message file and cleans it before the commit object is written.
pre-push checks commit messages that are about to leave the machine and rejects a matching explicit credit.

Chaining matters. If the repository already has a hook, the tool preserves and runs it as part of the local hook chain. This makes the guardrail additive instead of silently replacing existing repository behavior.

You can inspect the resulting files with normal Git commands or by looking in .git/hooks. The hook files are local repository state, not files committed to the project.

Reproduce the cleaning behavior

Create a temporary message file with both a line that should be removed and a line that should remain:

cat > /tmp/ai-credit-message.txt <<'EOF'
Document local hooks

Generated with Claude Code
Co-authored-by: Claude <noreply@anthropic.com>
Reviewed in Cursor
EOF

Run the cleaner:

ai-credit-scrub clean /tmp/ai-credit-message.txt
cat /tmp/ai-credit-message.txt

Expected output is equivalent to:

Document local hooks
Reviewed in Cursor
ai-credit-scrub: removed 2 explicit credit block(s)

The important distinction is that the tool matches complete, explicit credit signatures. A product name alone is not treated as a credit, so a sentence such as Reviewed in Cursor remains available for normal review context.

For a read-only check, use:

ai-credit-scrub scan CHANGELOG.md

Use scan when you want findings without changing the file. Use clean --in-place when you intentionally want a source text file rewritten.

Protect pull request text too

Git hooks cover commits and pushes, but a pull request title and body are not part of Git history. Create the pull request through the local wrapper:

ai-credit-scrub pr create \
  --title "Document local hooks" \
  --body-file pull-request.md

The wrapper cleans the supplied title and body, then delegates to your existing local gh pr create authentication. It does not require an ai-credit-scrub account, a hosted service, or an additional token.

This boundary is easy to miss when working with agents. An agent that calls a separate GitHub-writing integration can create a pull request without invoking local Git at all. In that workflow, the local Git hooks cannot see the request body. The project's integration guide recommends instructing the agent to use this wrapper, or using a local sanitizing proxy that is the only GitHub-writing server available to the agent.

Add a reviewed custom rule

The built-in signatures cover explicit credits for Codex, Claude Code, Cursor, Windsurf, and GitHub Copilot. You can add project-specific patterns with a configuration file:

version: 1
reviewed: true
literals:
  - "Internal agent credit"
regex:
  - '(?m)^Generated by ExampleBot\\.?$'
exclude:
  - "historical example"

The reviewed: true acknowledgement is deliberate. Custom rules can create false positives, so review their matches before enabling them. The project asks contributors to provide both a removal fixture and a false-positive fixture for new signatures.

Install a custom configuration only after reviewing it:

ai-credit-scrub scan --config .ai-credit-scrub.yml CHANGELOG.md

Keep historical examples, legal notices, and human contributor credits out of broad patterns. A conservative rule that misses an ambiguous sentence is safer than a rule that silently removes meaningful attribution.

Why this works

The design places enforcement at three different points in the local publication path:

Before commit creation, commit-msg rewrites the temporary message.
Before a remote update, pre-push checks outgoing commit messages.
Before a pull request API call, the wrapper cleans the title and body.

That separation reflects what each interface can actually control. The tool does not pretend that a Git hook can intercept every remote API or rewrite shared history safely. It keeps cleaning and checking local, deterministic, and offline-first. Only the pull request wrapper needs network access, and that call is made by the user's already-authenticated gh installation.

Failure modes and limits

There are several boundaries to understand before treating this as a complete publication policy:

git commit --no-verify bypasses the commit hook. The pre-push hook can still catch the escaped credit.
git push --no-verify bypasses the final local check too. Treat it as an intentional override.
A pull request created directly in the GitHub website or by an independent GitHub MCP server bypasses Git hooks.
The tool does not rewrite Git author or committer identity.
Removing a credit may conflict with an organization's contributor agreement, disclosure policy, or applicable law. Confirm the policy before enabling the rule.
The repository documents local enforcement, not CI enforcement. A CI job can report a problem, but it does not provide the same pre-publication boundary.

The v1.1.0 release also reports its dependency and toolchain status separately from these policy limits. In a clean checkout, go test ./... passed five tests, go vet ./... reported no issues, and the CLI smoke path passed. Those checks demonstrate the documented path, not a security guarantee or coverage of every Git client.

FAQ

Does this remove every mention of an AI tool?

No. It targets explicit credit lines and known trailers. A product name by itself is intentionally preserved.

Does it upload commit messages or source code?

Cleaning and checking require no network access and the project documents no hosted service or prompt upload. The pr create command delegates to your local GitHub CLI, so the normal gh network behavior still applies.

Does installing it destroy existing hooks?

The documented installer preserves and chains an existing hook. Still inspect the local result in a repository with important custom automation.

Can it protect a pull request created by an MCP server?

Not automatically. The MCP server must route through a local sanitizing boundary, or the agent must use ai-credit-scrub pr create.

Takeaway

If your team wants explicit AI credits out of public Git history, enforce that decision where the text is still local. ai-credit-scrub install --git covers commit creation and pushes, while ai-credit-scrub pr create covers the separate pull request boundary. The useful part is not the deletion itself. It is the narrow, reviewable policy and the honest list of places it cannot control.

Have you found more value in sanitizing commit messages, pull request text, or agent-specific configuration files first? Share the boundary that causes the most cleanup in your workflow.

AI assistance disclosure: This tutorial was prepared with AI assistance from the project's public documentation and a clean checkout of the v1.1.0 release. The commands and claims were checked against those sources and smoke-tested locally.

DEV Community: Fernando Paladini

Build a Citation-Ready Static Site with GEO Basics

Build a Citation-Ready Static Site with GEO Basics

TL;DR

What you will build

Prerequisites

Clone and inspect the site

Understand the page signals

Add crawler and agent context carefully

Run the project's validator

Verify a useful failure mode

Why this structure works

Failure modes and security boundaries

FAQ

Does GEO Basics require a framework?

Does JSON-LD guarantee an AI citation?

Is llms.txt required for Google Search?

What should I verify after deployment?

Takeaway

Fetch Multilingual Daily Reflections in Node.js with aa-daily-reflections

Fetch Multilingual Daily Reflections in Node.js with aa-daily-reflections

TL;DR

What you will build

Prerequisites

Start with the CLI

Use the JavaScript API

Add language and date validation

Verify the result reproducibly

Why the package is useful

Failure modes and security boundaries

FAQ

Does this package store the reflections locally?

Can I use Portuguese?

Is this an official AA integration?

Should I publish the returned text in my app?

Takeaway

Harness Score 1.8.0 No Longer Fails Closed-Source Repos for Missing Files

What leaves the score

What I scanned

Install 36 Local Developer Tools in Cursor with DevUtils MCP

TL;DR

Prerequisites

Install the plugin

Cursor

Claude Code

Any MCP client

Try a useful tool call

Verify the local transport

Why the wrapper is useful

Failure modes and limitations

Security and privacy boundaries

FAQ

Does the plugin send input to Fernando Paladini?

Do I need Cursor to use the server?

Should I use the plugin or manual configuration?

Is this a replacement for application code?

Takeaway

Sources

Measure an AI Coding Harness from L0 to L4 with Harness Score

TL;DR

Prerequisites

Start with an isolated copy

Establish a baseline

Climb the maturity ladder

L0 to L1: give the agent durable context

L1 to L2: scope guidance and protect hygiene

L2 to L3: add sensors and CI

L3 to L4: close the loop with hooks

Verify each transition

Failure modes and honest limits

FAQ

Does Harness Score inspect prompts or call an LLM?

Do I need Cursor to complete the tutorial?

Should I optimize for 108 out of 108?

Takeaway

Curate Verifiable ActiveAdmin 4 Themes with Markdown and CI

TL;DR

Prerequisites

1. Clone the directory and inspect the standard

2. Turn a compatibility claim into evidence

Is `llms.txt` required for Google Search?