DEV Community: Fernando Paladini

Build an Evidence-Friendly Bitcoin Timeline with Static HTML and TimelineJS

Fernando Paladini — Sun, 15 Nov 2026 12:39:44 +0000

Build an Evidence-Friendly Bitcoin Timeline with Static HTML and TimelineJS

A timeline can make a long technical history easier to explore, but a visual slider alone is not enough. If the events are hidden inside a third-party feed or rendered only after JavaScript runs, readers, search engines, and assistive tools have less context to work with.

This tutorial shows how to build a small static timeline from the open-source The History of Bitcoin repository. The project stores its event data in the repository, keeps a chronological HTML index in the page, and adds metadata for crawlers and answer engines. The result is an interactive timeline without a backend or database.

The project is educational. It is not investment advice, and historical price references are snapshots rather than predictions.

TL;DR

You will:

Clone the gh-pages branch.
Serve the files with Python's built-in HTTP server.
Inspect the local event data in assets/js/timeline-data.js.
Render it with TimelineJS.
Verify the page, metadata, and source links locally.

The repository is MIT licensed and currently documents 37 curated events from 2007 through June 30, 2026.

Prerequisites

You need:

Git.
Python 3.8 or newer with the py launcher on Windows, or python3 on macOS and Linux.
A browser.
Basic HTML and JavaScript familiarity.

The published project uses the gh-pages branch directly. It is a static site, not a package with a versioned release. That means you should treat the branch contents you clone as the source snapshot you are reviewing.

1. Run the existing timeline

Clone the branch and start a local server:

git clone --branch gh-pages --depth 1 https://github.com/paladini/bitcoin-history.git
cd bitcoin-history
python -m http.server 8058

On Windows PowerShell, the equivalent command is:

py -3 -m http.server 8058

Open http://127.0.0.1:8058/. The expected result is a page titled â€œThe History of Bitcoin: Interactive Timeline (2007-2026)â€ with a TimelineJS navigation area, a chronological event index, and an educational disclaimer.

The repository's README documents the same local server path. In a smoke test of the current branch, the page returned HTTP 200 and served the expected HTML.

2. Understand the data boundary

The important design choice is that the timeline data lives in the repository instead of a live spreadsheet. Open assets/js/timeline-data.js. It assigns a TimelineJS-compatible object to window.bitcoinHistoryTimelineData.

A simplified event has this shape:

{
  "start_date": {
    "year": "2008",
    "month": "10",
    "day": "31"
  },
  "text": {
    "headline": "The Bitcoin white paper is published",
    "text": "Satoshi Nakamoto publishes the original peer-to-peer electronic cash proposal."
  }
}

The actual repository keeps the dates and text as strings because that is the structure expected by TimelineJS. It also stores the title and the complete event array in the same file, so a reviewer can inspect the source without opening a database or calling an application API.

To add an event, append another object to the events array. Keep the date explicit, use a factual headline, and include a source link in the visible HTML index when the claim depends on a primary document.

3. Connect the data to TimelineJS

The end of index.html loads TimelineJS and then passes the local object to the constructor:

<script src="https://cdn.knightlab.com/libs/timeline3/latest/js/timeline.js"></script>
<script src="assets/js/timeline-data.js"></script>
<script>
  new TL.Timeline("timeline-embed", window.bitcoinHistoryTimelineData, {
    hash_bookmark: true,
    language: "en",
    timenav_position: "bottom"
  });
</script>

The order matters. The data file must load before the constructor runs. The timeline-embed element must also exist in the document:

<section id="history" aria-label="Interactive Bitcoin timeline">
  <div id="timeline-embed"></div>
</section>

The hash_bookmark option lets the selected event be represented in the URL. That makes a particular point in the timeline easier to share and revisit.

The project currently loads TimelineJS from Knight Lab's CDN. The event data is local, but the page is not fully self-contained offline because the library and stylesheet are external dependencies. If you need an offline archive, download and serve those assets locally, then verify their licenses and update the HTML references.

4. Keep a crawlable fallback

The interactive component is useful for exploration, but the page does not depend on it for all meaning. The current HTML also contains:

A visible summary of the covered period.
An ordered list of chronological milestones.
time elements with machine-readable dates.
Source links for selected historical and regulatory claims.
A disclaimer that separates education from investment advice.

This fallback is valuable when JavaScript fails, when a crawler reads the raw HTML, or when a reader wants to scan the chronology without operating a visual control.

A simple event entry looks like this:

<li>
  <time datetime="2024-01-10">January 10, 2024</time>
  - The SEC approves spot Bitcoin exchange-traded products.
  <a href="https://www.sec.gov/newsroom/speeches-statements/gensler-statement-spot-bitcoin-011023">
    Source
  </a>
</li>

The visible list should stay synchronized with the JavaScript data. A practical workflow is to update the data object first, then add the same event to the HTML index, then run a local review.

5. Add metadata without hiding the content

The current page uses ordinary HTML metadata rather than relying only on the interactive widget. It includes a canonical URL, a description, Open Graph fields, a Twitter card, Dublin Core fields, and JSON-LD.

The JSON-LD describes the page as a web page, article, image, breadcrumb, and item list. The repository also publishes robots.txt, sitemap.xml, and llms.txt.

These files do not replace good content. They make the page's identity, language, date range, license, and update date easier for different consumers to interpret. Use descriptive titles and headings, keep the canonical URL stable, and ensure that metadata matches the visible page.

6. Verify changes reproducibly

After editing an event, repeat the same checks:

python -m http.server 8058

Then verify:

The page returns HTTP 200.
The browser shows the timeline and the chronological index.
The selected event updates the URL hash.
The event appears in both timeline-data.js and the HTML list.
Source links open the intended primary pages.
The disclaimer remains visible.
No API key, wallet credential, or private data was added.

For a command-line smoke test, request the local page:

curl -I http://127.0.0.1:8058/

A successful response should include HTTP/1.0 200 OK or an equivalent HTTP 200 status from the local Python server.

Why this structure works

The repository separates three concerns:

timeline-data.js is the structured event source for the visualization.
index.html provides the readable fallback and metadata.
robots.txt, sitemap.xml, and llms.txt describe how the published page can be discovered.

That separation is small enough to review in a pull request. It also avoids making the interactive library responsible for facts, source attribution, or the page's entire information architecture.

Failure modes and limitations

If the timeline is blank, check that the external TimelineJS script loaded, that timeline-data.js appears before the constructor, and that the timeline-embed element exists.

If the page works locally but not on a host, check the base path, case-sensitive asset names, and HTTPS mixed-content rules. GitHub Pages serves the project under /bitcoin-history/, so relative asset paths are safer than root-relative paths.

The project is a curated historical view, not a complete ledger of every Bitcoin event. Some entries include price snapshots, which can become stale. Regulatory and institutional claims can also require updates as official sources change. The MIT license permits reuse, but reused copies should preserve attribution and should not imply that the original author endorses financial decisions.

FAQ

Does this need a database?

No. The current project keeps the event data in a JavaScript file and publishes static HTML.

Is it fully offline?

Not as published. The event data is local, but TimelineJS is loaded from a CDN. Self-host the library and stylesheet if offline operation is a requirement.

Is this an investment tool?

No. It is an educational chronology. It does not predict prices, recommend assets, or manage wallets.

Can I add my own milestones?

Yes. Add a dated object to the event array and mirror it in the HTML index. Cite a primary source for claims that readers may want to verify.

Takeaway

A useful historical visualization does not have to begin with a database. A local event file, a readable HTML fallback, explicit sources, and a small client-side renderer are enough to build something interactive and reviewable.

AI assistance disclosure: AI assistance was used to organize this tutorial and improve its wording. The repository behavior, file names, current branch, license, and smoke-test results were checked against the linked primary sources.

What would you add first: more historical events, local self-hosted TimelineJS assets, or automated checks that compare the HTML index with the JavaScript event data?

Build a Reproducible POSCOMP Study Library from an Open Source Archive

Fernando Paladini — Sat, 14 Nov 2026 12:40:37 +0000

Preparing for a large exam often starts with a familiar problem: the material exists, but it is scattered across old links, downloaded files, and personal notes. That makes it difficult to answer a simple question: which exams and answer keys do I actually have, and can someone else reproduce my setup?

The awesome-poscomp repository solves the archive part of that problem. It collects POSCOMP exam papers and answer keys in one public Git repository, with a year-by-year index. POSCOMP is the Brazilian national exam commonly used in admission processes for graduate computing programs. The official SBC POSCOMP page is the authority for the exam itself; the repository is a convenient, reviewable study archive.

This tutorial shows how to create a local study library, verify that the repository is the one you intended to use, and inspect the available years without relying on an opaque download folder.

TL;DR

Clone paladini/awesome-poscomp, inspect its README and license, list the local PDF files, and compare the result with the repository index. Keep the repository commit with your notes so the study setup can be reproduced later.

Prerequisites

You need:

Git 2.x installed and available on your PATH.
A PDF viewer. A command-line PDF text tool is optional.
A Windows PowerShell, macOS, or Linux shell.
Enough disk space for the archive and any notes you add.

The repository is public and uses the MIT license. It is an archive of study material, not an official registration system, score calculator, or guarantee that a particular graduate program accepts a result. Check the official SBC material and the rules of the program you are applying to.

1. Clone a known revision

Start with a dedicated directory. The URL below is the public repository URL, so the command is independently checkable.

git clone https://github.com/paladini/awesome-poscomp.git
cd awesome-poscomp

Record the revision used for your study plan:

git rev-parse --short HEAD
git remote -v

The current default branch is master. A commit identifier matters because an archive can gain a new exam or fix a link later. If you share a study checklist with another person, include the commit hash beside it.

2. Read the index before opening PDFs

The repository README is the catalog. It groups the collection by year and links to a question booklet and an answer key when both are available. It currently describes material from 2002 through 2024 and includes a provisional 2025 entry.

Open the README in a browser or inspect it from the shell:

git show HEAD:README.md

The index is useful for two reasons. First, it tells you whether a local file is expected for a particular year. Second, it distinguishes a repository-hosted PDF from a link to an external SBC, university, or publication host. That distinction matters when a link stops working: the repository can preserve some files locally, but it cannot guarantee the availability of an external website.

3. Build a local inventory

On macOS or Linux, list the PDFs with:

find poscomp -type f -iname '*.pdf' | sort

On PowerShell, use:

Get-ChildItem -Path .\poscomp -Recurse -File -Filter *.pdf |
  Sort-Object FullName |
  Select-Object -ExpandProperty FullName

The output gives you a concrete inventory instead of a vague claim that the archive is complete. You can save it as a review artifact without changing the repository:

find poscomp -type f -iname '*.pdf' | sort > poscomp-pdfs.txt

The file names should make the role of each document clear, such as a question booklet or a gabarito. Do not assume that every year has the same local layout. The README is the source for what each link means.

4. Check that the PDFs are readable

Open one question booklet and its answer key for a recent year, then repeat the check for an older year. This catches incomplete downloads and viewer problems early.

If pdfinfo is installed, you can inspect the document metadata:

pdfinfo poscomp/2024/poscomp_caderno_prova_2024.pdf
pdfinfo poscomp/2024/poscomp_prova_gabarito_2024.pdf

The exact file names may change as the archive evolves, so use the paths returned by your inventory command. A successful metadata read is only a basic integrity check. It does not prove that every answer is correct or that a PDF is an official publication.

For a stronger local check, extract a few pages to text when your PDF tools support it:

pdftotext -f 1 -l 2 poscomp/2024/poscomp_caderno_prova_2024.pdf -

Look for a title, year, or question heading. This is a reproducible sanity check, not a replacement for reading the source document.

5. Turn the archive into a study loop

A repository becomes useful when it supports a repeatable decision process. Pick one year and one subject area from the program topics listed in the README, then work through the question booklet without consulting the key. Save your answers outside the cloned repository or on a separate branch.

After the attempt, compare with the answer key and record only the questions that need review. The README groups the content into areas such as mathematics, foundations of computing, and computing technology. That makes it possible to build a small backlog instead of rereading every subject after every practice session.

For example, a simple weekly routine can be:

Select one available year from the index.
Complete a bounded set of questions under a fixed time limit.
Compare answers with the matching key.
Tag missed questions by topic.
Repeat the same topic with another year.

The important detail is the evidence trail. Keep the repository commit, year, PDF path, and your notes together. If a link is later corrected, you can tell which source you used at the time.

Expected result

At the end, you should have a local checkout with an identifiable Git revision, a list of available PDFs, and a study note that points to exact files. A minimal verification report might contain:

Repository: paladini/awesome-poscomp
Revision: <output of git rev-parse --short HEAD>
Archive index: README.md
Recent sample: poscomp/2024/
Older sample: <path selected from the local inventory>
Integrity check: PDF metadata and first-page text read successfully

This result is more useful than a folder named poscomp-final, because another person can reproduce the same starting point and see which parts came from the public archive.

Why the Git workflow helps

Git provides three practical properties for study material. The remote URL identifies the source. The commit hash identifies the exact snapshot. A text inventory identifies the files you actually used. Together, those properties reduce accidental mixing of answer keys from different years or silently missing documents.

The workflow also keeps the boundary between community-maintained convenience and official information visible. The repository links to the SBC and other public sources, but it does not replace them. Always verify current exam dates, registration rules, and program requirements with the responsible institution.

Failure modes and limitations

If git clone fails, check network access and the repository URL. If a PDF is missing, compare your local tree with the README because some entries point to external sites rather than repository files. If a PDF opens but has no selectable text, use a viewer or OCR tool carefully and treat extracted text as a convenience layer.

The archive does not automatically grade answers, generate a personalized curriculum, or certify that a question set is current. It also cannot guarantee that external links remain available. The repository license permits reuse under its terms, but the individual exam documents can have their own provenance and publication context. Preserve source links and attribution when redistributing material.

FAQ

Is this the official POSCOMP website?

No. The SBC POSCOMP page is the official starting point for exam information. This repository is a public study archive.

Do I need to install a programming language?

No. Git and a PDF viewer are enough for the basic workflow. PDF command-line tools are optional verification helpers.

Should I edit the cloned repository with my answers?

Keep personal answers and annotations separate unless you intentionally want to create a reviewable fork. A separate notes directory makes it easier to update the archive without merging personal files into source material.

Can I rely on the newest year shown in the README?

Treat each entry according to its label. A provisional or external link needs separate confirmation. Check the official SBC publication before treating a document as authoritative for a current exam.

Takeaway

awesome-poscomp turns a scattered set of POSCOMP references into a reviewable Git starting point. Clone it, record the revision, inventory the PDFs, verify representative files, and keep your study notes tied to exact paths. That small amount of provenance makes a personal preparation workflow easier to reproduce and safer to update.

Have you found a useful way to turn past POSCOMP questions into a topic-based review backlog without losing the source year and answer-key provenance?

Disclosure: AI assistance was used to organize and edit this tutorial. The repository links, commands, and limitations were checked against the public project and official POSCOMP source pages.

Install a Local MCP Utility Plugin in Cursor with DevUtils

Fernando Paladini — Fri, 13 Nov 2026 12:36:43 +0000

AI assistants are useful at explaining code, but they should not improvise a SHA-256 digest, decode a JWT by hand, or guess whether an IP address belongs to a subnet. Those are small, deterministic operations that deserve a tool with a clear contract.

DevUtils MCP Plugin packages that idea for Cursor and Claude Code. It installs a local MCP server with utilities for hashing, encoding, UUID generation, JWT inspection, JSON, network calculations, and text processing. The plugin wrapper is open source under the MIT license, and its configuration starts the server through npx on your own machine.

This tutorial installs the plugin, shows the equivalent configuration, verifies the MCP stdio handshake, and explains the boundary between local processing and package downloads.

TL;DR

Install DevUtils MCP from Cursor Settings, enable the devutils server, and ask your assistant to use a deterministic utility such as UUID generation or JSON validation. The plugin manifest is version 1.0.7 on the repository's current branch. The wrapped devutils-mcp-server package requires Node.js 18 or newer.

The server exposes 36 tools. They run locally after the package is available, so the inputs you send to a tool are handled by the local MCP process rather than an API operated by the plugin author.

Prerequisites

You need:

Cursor with MCP support, or Claude Code with plugin support.
Node.js 18 or newer. The server README recommends Node.js 22.
Permission to let npx download devutils-mcp-server the first time it runs.

The plugin repository is paladini/devutils-cursor-plugin. It is a wrapper and distribution package. The implementation of the 36 utilities lives in the related devutils-mcp-server repository.

Install it in Cursor

The repository documents this path for Cursor:

Open Cursor Settings.
Open Customize.
Search for DevUtils MCP.
Select Install.
Enable the devutils MCP server under Customize > MCPs.

You can also choose Add from GitHub and enter paladini/devutils-cursor-plugin. The repository's Cursor manifest names the plugin devutils-mcp, declares version 1.0.7, and points its MCP configuration at the devutils server.

After enabling it, start with a request that has an observable result:

Use the DevUtils MCP server to generate one UUID v4 and return only the UUID.

The important detail is the request's explicit tool choice. It gives you a way to distinguish an MCP result from an answer the model generated without calling the server.

What Cursor is launching

The plugin contains this small stdio configuration:

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

npx -y can download the package when it is not already available. Once started, the MCP server communicates over standard input and standard output. The plugin does not add a web endpoint, API key, or remote service.

If your client does not support the plugin marketplace, the server README documents the same command for manual MCP configuration. For example, a client that uses an mcpServers object can reuse the JSON above. Keep the command and arguments unchanged unless you have a deliberate reason to pin or replace the package source.

Verify the connection without guessing

You can test the server boundary outside Cursor with a JSON-RPC initialize message. This is a protocol smoke test, not a test of every utility:

$message = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0"}}}'
$message | npx -y devutils-mcp-server

A successful response contains a JSON-RPC result with server information and a tools capability. The server also writes a short startup line to stderr. Seeing the response confirms that Node.js can resolve the package and that the process accepts MCP input over stdio.

For a client-level verification, ask Cursor to perform a simple operation and then repeat it with a known local value:

Use DevUtils to calculate the SHA-256 hash of the exact string: hello

The result should be deterministic. You can compare it with a local command such as Get-FileHash for a file, or with a trusted library for a string. The point is not that MCP is faster than a native library. The point is that an assistant can call a named operation with a defined input instead of inventing a result.

Useful operations to try

The server README groups the tools into eight areas:

Hashing: MD5, SHA-1, SHA-256, SHA-512, bcrypt generation, and bcrypt verification.
Encoding: Base64, URL, HTML entity, and hexadecimal conversions.
Generators: UUID v4, Nano ID, passwords, and random hex values.
JWT: decoding and structure or expiration validation.
JSON: formatting, validation, and dot-notation queries.
Converters: timestamps, number bases, colors, and byte units.
Network: CIDR calculations and IPv4 or IPv6 classification.
Text: case conversion, slugs, regular-expression checks, statistics, and diffs.

These are good assistant tasks because each one has a compact input and an inspectable output. For example:

Use DevUtils to validate this JSON and explain the error location: {"enabled": true,}

Or:

Use DevUtils to calculate the network and host range for 192.168.10.0/24.

Do not send a real password, production token, customer record, or private document just to test the integration. Use synthetic values first.

Why the local boundary matters

The plugin's privacy policy says the tools process inputs on the local machine and that the plugin author does not collect or transmit them. That is a property of this plugin and server design, not a general guarantee about every MCP client or every package installed through npx.

There is still a network step: npx may fetch the npm package. The repository documents npm as a third-party service involved in that download. After the package is available, the server is intended to run locally and its README states that the utilities use no external APIs.

The security policy also makes the scope clear: the wrapper adds no network endpoints, while input validation and dependency updates belong to the server implementation. Review the server source and package provenance before using it with sensitive workflows.

Failure modes and limits

The server does not appear in Cursor

Check that the plugin is installed and that devutils is enabled under the MCP settings. Then verify node -v in a terminal. A missing Node.js installation prevents the npx command from starting.

`npx` cannot download the package

This is usually a registry, proxy, permission, or network problem. Run npx -y devutils-mcp-server directly and inspect the error. Do not treat a successful plugin installation as proof that the runtime package is available.

The assistant answers without using the tool

Ask it to name the DevUtils operation explicitly, then look for an MCP tool call in the client transcript. A plausible-looking answer is not verification.

You need application-level performance

Use a native library directly inside your application. The project itself says DevUtils is intended for AI-agent workflows, not as a replacement for optimized application code. MCP adds a process and protocol boundary.

You need a security guarantee

Do not infer one from the word “local.” Local software can still have bugs, compromised dependencies, unsafe inputs, or an overly privileged client. Pin dependencies where your deployment policy requires it, review the package source, and keep secrets out of exploratory prompts.

FAQ

Does the plugin require an API key?

No. The documented configuration starts the local server with npx, and the repository describes zero external API calls.

Can I use it without Cursor?

Yes. The server can be configured directly in other MCP-compatible clients. Claude Code can install the plugin with /plugin marketplace add paladini/devutils-cursor-plugin followed by /plugin install devutils-mcp@devutils-cursor-plugin.

Is the plugin the same as the server?

No. The plugin repository supplies manifests and client installation metadata. The related server repository contains the MCP implementation and utility tools.

Are JWTs sent to a cloud service?

The plugin documentation says JWT processing happens locally. Even so, use test tokens while evaluating the setup and verify the behavior of the exact client and package version you deploy.

Takeaway

DevUtils is a small, practical way to give an MCP-capable assistant deterministic developer utilities without adding a custom API service. Install the plugin, verify the stdio handshake, and start with synthetic inputs. The useful security habit is to understand both boundaries: package acquisition may use npm, while the tool operations are designed to execute locally.

Have you found a developer task where a deterministic MCP utility prevents more errors than a general-purpose coding assistant alone?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, versions, configuration, project metadata, and security notes were checked against the linked primary sources and a local MCP initialize smoke test.

Give Your Coding Agent Semantic Code Navigation with Locus MCP

Fernando Paladini — Thu, 12 Nov 2026 12:42:03 +0000

Text search is useful until an AI coding agent has to answer a structural question: where is this symbol really defined, which callers will a refactor affect, or what type does this expression have? A grep result can show matching text, but it cannot reliably distinguish a definition from a re-export, a comment, or an unrelated variable with the same name.

Locus MCP adds a small semantic layer to that workflow. It connects an MCP-compatible agent to language servers, so the agent can ask for definitions, references, hover information, diagnostics, status, and a rename preview through six focused tools.

This tutorial sets up Locus for a TypeScript project, checks the language-server boundary, and adds an MCP configuration that an agent host can start automatically. The goal is not to replace an IDE or make refactors autonomous. The goal is to give an agent better evidence before it edits code.

TL;DR

Install a language server, run Locus initialization and checks, then add the server to your agent configuration:

npm install -g typescript-language-server typescript
npx -y @paladini/locus-mcp init
npx -y @paladini/locus-mcp check

The current npm package is @paladini/locus-mcp@0.1.5 and requires Node.js 22 or newer. Pin that version in repeatable setup scripts when you do not want a moving latest tag.

Prerequisites

You need:

Node.js 22 or newer.
An MCP-compatible host such as Cursor, Codex, or Claude Code.
A project containing source files that a supported language server can analyze.
The relevant language server on your PATH.

For TypeScript and JavaScript, the repository documents typescript-language-server and typescript. Python, Go, and Rust use separate language servers described in the Locus getting started guide.

Locus itself does not bundle those language servers. That separation matters: Locus provides the MCP and LSP client layer, while the language server remains an independently installed tool with its own version and configuration.

1. Install and initialize Locus

Install the TypeScript language server globally, then initialize the project from its root:

npm install -g typescript-language-server typescript
npx -y @paladini/locus-mcp init

The documented init command generates locus.toml and locus.json without replacing existing configuration files. Keep the generated files under version control if the project team wants a shared language-server setup. Use a project-scoped configuration when different repositories need different server choices.

Now check whether the required binaries are visible:

npx -y @paladini/locus-mcp check

The check is intentionally honest. It reports available and missing binaries instead of pretending that a language can be analyzed. A missing server is a setup problem, not an LLM failure.

2. Verify the local boundary

Before connecting an agent, inspect the generated files. A minimal configuration can look like this:

{
  "root": ".",
  "servers": [
    {
      "id": "typescript",
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx"]
    }
  ]
}

The exact schema and built-in defaults are maintained in the Locus configuration reference. When the server list is empty, Locus uses built-in defaults. Custom entries are useful when a project needs a non-default binary, additional arguments, or a narrower extension mapping.

The package also exposes a status MCP tool. It reports language-server readiness and missing binaries, while diagnostics can report file or workspace problems. These results should be treated as evidence with a scope and a timestamp, not as a guarantee that the whole project is correct.

3. Add Locus to your agent host

Locus is normally started by the host over stdio. You do not need to run serve manually for the normal MCP configuration.

For Cursor, create or edit .cursor/mcp.json in the project:

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp@0.1.5", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

For Codex, the repository documents the equivalent TOML configuration:

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp@0.1.5", "serve"]
cwd = "/absolute/path/to/your/project"

Use the host's normal reload or restart action after saving the configuration. Then ask the agent to locate a symbol and list its references. A useful first request is: "Use Locus to find the definition of UserService and list its references."

What the six tools change

The value is not the number six. It is the division of labor between the agent and the language server:

locate finds a symbol definition or lists symbols in a file.
refs finds references or implementations at a position.
hover returns type information and documentation.
diagnostics reports file or workspace diagnostics.
status shows server readiness and binary availability.
rename previews a rename and can return an apply plan.

That last tool is worth treating carefully. A rename preview is not the same as an approved write. Locus can prepare a plan, but your agent still decides whether and how to apply edits. This keeps the tool focused on code intelligence instead of turning it into an autonomous refactoring system.

Reproducible verification

You can verify the installation without asking an agent to edit your repository:

npx -y @paladini/locus-mcp init
npx -y @paladini/locus-mcp check
npx -y @paladini/locus-mcp warm

init is idempotent according to the repository's CLI tests, so running it again should preserve existing configuration. warm starts configured language servers early, which can make the first semantic request less surprising on a larger project. If a binary is missing, check can return a non-zero status. Install the missing language server and run the check again.

For a source-level verification of the project itself, the repository's current main checkout passed npm run build, npm run typecheck, and npm test. The test suite reported 94 passing tests and one skipped integration case because pyright-langserver was not installed in that environment. The same suite verified the TypeScript language-server integration and the six-tool MCP registration. These are repository checks, not a promise that every host or language configuration will behave identically.

Failure modes and limitations

The agent sees no symbols

Run locus check first. If the language server is missing, not executable, or mapped to the wrong file extension, semantic requests cannot succeed. Also confirm that the host passes the intended project directory through cwd.

The server is still starting

Language servers may need time to index a workspace. Locus exposes a server_starting result so the client can retry rather than treating a temporary startup state as a definitive absence of results. warm can move that startup earlier in the session, but it does not eliminate indexing cost.

Text search is still necessary

Locus does not replace grep. The repository explicitly positions ordinary text search as the right tool for comments, configuration keys, log lines, and other non-symbol content. Use semantic tools for code structure and text search for literal content.

Security and trust boundaries

Locus reads project files through language-server processes and communicates with the agent host over stdio. It does not provide a security guarantee for a language server, an editor host, or a third-party plugin. Keep language servers and agent hosts updated, review MCP configuration before enabling it, and avoid granting a tool more filesystem scope than the project requires.

The project is MIT licensed, but dependencies and language servers have their own licenses and security posture. Read the repository's security policy and the MIT license before redistributing or deploying it in a managed environment.

FAQ

Does Locus edit code?

No. Its tools provide navigation, diagnostics, status, and rename previews. Your agent's normal edit mechanism remains responsible for changing files.

Which editors are supported?

The documented setup includes Cursor, Codex, and Claude Code. The deeper requirement is an MCP-compatible host that can start a stdio server with a project working directory.

Do I need every language server?

No. Install only the servers for languages in the projects you want to analyze. status and check make missing binaries visible.

Is this a full IDE inside MCP?

No. Locus intentionally exposes six focused tools and complements the host. The project documents symbolic editing, agent memory, and a broad refactoring toolkit as out of scope.

Takeaway

An AI coding agent becomes easier to review when it can cite structure instead of guessing from matching text. Locus provides that bridge with a small MCP surface, explicit language-server prerequisites, and a dry-run-oriented rename flow. Start with one TypeScript project, verify check and status, then decide whether the extra semantic evidence improves your agent's refactoring workflow.

What would you verify first in your own repository: definitions, references, diagnostics, or rename previews?

AI assistance disclosure: AI was used to help organize and edit this tutorial. The commands, package metadata, repository documentation, license, and test results were checked against the public Locus sources and a local checkout before publication.

Install Reviewable Agent Skills with the Tech Leads Club CLI

Fernando Paladini — Wed, 11 Nov 2026 12:37:45 +0000

AI coding agents become more useful when they can follow a repeatable workflow, but copying prompt folders between projects creates a quiet maintenance problem. A skill can be duplicated, overwritten, or installed into the wrong agent directory without leaving much evidence.

This tutorial uses the open-source Tech Leads Club agent-skills repository and its @tech-leads-club/agent-skills CLI to install one skill into a project. The result is deliberately small: a pinned installation, a copied skill directory, and a lockfile that records what happened.

The commands below target the repository's stable v1.4.10 tag. That tag declares Node.js 24 or newer and the CLI package is MIT licensed. The repository also contains skill content with separate attribution requirements, so read the license notes before redistributing a skill.

TL;DR

Use the CLI's non-interactive form when you already know the skill and target agent:

npx --yes @tech-leads-club/agent-skills@1.4.10 install -s tlc-spec-driven -a cursor

From the project directory, this installs tlc-spec-driven as a copy under .cursor/skills and records the operation under .agents/.skill-lock.json. The exact result depends on the catalog and the agent configuration available when you run it.

Prerequisites

You need:

Node.js 24 or newer, matching the v1.4.10 CLI package engine.
A project directory where you can create .cursor/ and .agents/.
Network access for the first catalog download.
A compatible agent directory. This example uses Cursor.

The repository's README lists interactive and command-line workflows. This tutorial uses the command-line path because it is easier to reproduce in a clean directory and does not require raw terminal input.

Install one skill locally

Create a temporary project or open an existing project where the skill should live:

mkdir agent-skills-demo
cd agent-skills-demo

Run the pinned CLI command:

npx --yes @tech-leads-club/agent-skills@1.4.10 install -s tlc-spec-driven -a cursor

The -s option selects the skill by catalog name. The -a option selects the target agent. Because neither -g nor --global is supplied, the installation is local to the current project. The default method is copy, which makes the installed files visible in the project and avoids making the project depend on a local symlink.

On a successful run, the CLI reports that one skill was installed for Cursor. The repository's documented alternative is --symlink, but that changes the trust and portability model: the target depends on a link that can point somewhere outside the project. Use it only when that relationship is intentional.

Verify the result

Inspect the two artifacts created by the operation:

agent-skills-demo/
  .agents/
    .skill-lock.json
  .cursor/
    skills/
      tlc-spec-driven/
        SKILL.md

The exact skill may contain additional references/ or scripts/ directories. The important checks are that the skill directory is inside the selected agent directory and that the lockfile names the installed skill.

On Windows PowerShell, use:

Get-ChildItem -Force .cursor\skills\tlc-spec-driven
Get-Content .agents\.skill-lock.json

The lock entry should identify tlc-spec-driven, the cursor agent, the copy method, and a content hash. In my clean checkout, the command completed successfully and created those two project-local paths. Treat the hash as an integrity record for the installed content, not as proof that the skill is safe for every use.

You can also confirm the CLI version without entering the interactive interface:

npx --yes @tech-leads-club/agent-skills@1.4.10 --version

The expected version is 1.4.10. Pinning the version makes a future rerun explicit instead of silently selecting a newer package.

Why the lockfile matters

The project describes .agents/.skill-lock.json as the source of truth for installed skills. The security policy says the lockfile is validated with a strict schema, written through a backup and temporary file, and populated with content hashes. That gives a team a reviewable record of which catalog item was installed and which content was copied.

This is more useful than treating a skill directory as an opaque prompt bundle. A reviewer can inspect the SKILL.md files, compare the lock entry, and decide whether an update should be accepted. The CLI also keeps an audit log for install, update, and remove operations according to the project's security documentation.

Security boundaries to understand

The project documents several defenses, but they are boundaries to evaluate, not a universal security guarantee.

First, the CLI sanitizes names and checks resolved paths before reading, writing, or deleting files. Its security policy specifically describes path traversal and symlink checks. This reduces the risk that a skill name escapes the intended installation directory.

Second, the catalog is still content that can influence an AI agent. Read the skill before enabling it, especially when it references shell commands, network access, credentials, or external services. A readable file is auditable, but readability does not make every instruction trustworthy.

Third, the MCP server described by the project is a separate component. The security policy describes it as read-only, local over stdio, and limited to catalog files. Do not generalize those properties to every skill or to the CLI's installation behavior.

Finally, the repository says some skill files use CC-BY-4.0 while the software engine uses MIT. If you copy a skill into a distribution, check that skill's own attribution and license before publishing it.

Common failure modes

Node.js is too old

The v1.4.10 package declares node >=24. An older runtime can fail before the CLI starts. Check node --version and install a supported Node.js release before debugging the catalog.

The skill name is not found

Catalog names are exact. Start with a documented name such as tlc-spec-driven, and avoid guessing a directory name from a display title. The interactive mode is useful when you need to browse the catalog, but it requires a real terminal with stdin support.

The command fails in a redirected process

The list command renders an interactive interface. In a non-interactive process without raw stdin support, it can fail before showing the catalog. Use a terminal for browsing, or use the explicit install -s ... -a ... form when the skill and agent are already known.

A symlink behaves differently on another machine

Symlinks depend on filesystem permissions and path layout. The documented default is copy. Prefer the default for a portable project, then review the copied files as part of the change.

A rerun changes the installed content

Do not assume the catalog is immutable forever. Pin the CLI version, inspect the lockfile, and review updates before accepting them. The repository's content hashing helps detect changes, but your review still determines whether the new skill belongs in the project.

FAQ

Does this install a skill globally?

No. The example omits -g, so it targets the current project. Add the global option only when you intentionally want the skill under the user's agent configuration.

Can I install more than one skill?

Yes. The README documents multiple names after -s, for example agent-skills install -s aws-advisor coding-guidelines docs-writer. Keep the set small enough to review, and verify the resulting lockfile.

Does the CLI validate the quality of every skill?

It provides catalog, integrity, and installation controls. Those controls do not replace human review of a skill's instructions, references, scripts, or license.

Why pin `1.4.10` instead of using `npx` without a version?

An unpinned command can resolve a different release later. A versioned command keeps the documented behavior and the verification target aligned.

Takeaway

A local agent skill should be treated like a dependency with a filesystem destination, an integrity record, and a review boundary. Pin the CLI, install with an explicit skill and agent, inspect .cursor/skills and .agents/.skill-lock.json, and keep the default copy method unless a symlink is a deliberate choice.

What would you add to your team's review checklist before allowing a new agent skill into a repository?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, version, installation result, repository details, and security boundaries were checked against the v1.4.10 project sources and a clean local package installation.

Primary sources: v1.4.10 README, CLI package metadata, security policy, MIT license and attribution note, and the stable Git tag.

Block Accidental AI Credits Before Git Publishes Them with Go

Fernando Paladini — Wed, 11 Nov 2026 02:27:05 +0000

failed to write kernel assets: The system cannot find the path specified. (os error 3)

Build a Multilingual React Reflection Portal with GitHub Pages

Fernando Paladini — Mon, 09 Nov 2026 14:35:08 +0000

If a daily-content project starts as a folder of JSON files, the first useful web interface does not need a database server. It needs a predictable data shape, a small client-side state model, and a deployment target that can serve static files.

This tutorial builds that path with AA Daily Reflections Database, an open-source React portal that publishes English, Spanish, French, and Brazilian Portuguese data as JSON, CSV, and SQLite. The goal is not to reproduce its reflection text here. The goal is to understand the reusable engineering pattern: select a language, select a date, load one static data file, and deploy the result as a static site.

TL;DR

Clone the repository, install its Node.js dependencies, run the data-copy step, and build the React app. The portal keeps the selected language and date in localStorage, fetches the matching language JSON from public/data, and uses PUBLIC_URL so the same build can work locally or beneath a GitHub Pages project path.

The repository currently targets React 18.2.0 and react-scripts 5.0.1 in package.json. The live site is available on GitHub Pages.

Prerequisites

You need:

Node.js and npm
Git
A browser
A GitHub repository if you plan to publish your own fork

The project also includes Python, PHP, Go, and JavaScript examples for reading the SQLite database. This walkthrough focuses on the React portal and its static JSON boundary. See the repository's examples guide for the other language-specific paths.

1. Get the project and inspect the data boundary

Clone the repository and enter it:

git clone https://github.com/paladini/aa-daily-reflections-database.git
cd aa-daily-reflections-database

The repository stores the browser-facing files in public/data. Each JSON record has a date, language, title, quote, reflection text, and source reference. The data README documents the same fields and also shows the SQLite schema.

That separation matters. The React app does not need a server endpoint for every date. It can fetch one language file, keep it in memory, and find the requested date locally. Static hosting is enough for this read-only workflow.

2. Install dependencies and build the portal

Install from the lockfile, then run the production build:

npm ci
npm run build

The prebuild script runs npm run copy-data first. That script copies the four language files into public/data, which is the location the browser service reads at runtime. The build then emits a static build directory.

If you want to inspect the development version before building, run:

npm start

Open the local address shown by Create React App. The application uses the current date as its initial selection and starts in Brazilian Portuguese. You can change both values from the interface.

3. See how language selection becomes a file request

The central mapping lives in src/context/AppContext.js. It maps an application language key to a concrete public filename:

export const LANGUAGES = {
  'pt-br': {
    code: 'pt-br',
    name: 'Portuguese (Brazil)',
    file: 'daily_reflections_brazilian-portuguese.json',
  },
  en: {
    code: 'en',
    name: 'English',
    file: 'daily_reflections_english.json',
  },
};

The current source contains all four languages. The important design choice is that the UI does not construct arbitrary paths from user input. It selects a file from a fixed allowlist. That keeps the fetch boundary easy to audit.

The same context stores language and selectedDate, then persists them under two local-storage keys. A visitor can return later and keep the last selected language and date on that browser. This is convenience state, not account data, and it never needs a server session.

4. Load one language file and find one date

The data service in src/services/reflectionService.js caches each loaded language file. Its core path is equivalent to this:

const dataCache = {};

const loadLanguageData = async (lang) => {
  if (dataCache[lang]) return dataCache[lang];

  const languageInfo = LANGUAGES[lang];
  const baseUrl = process.env.PUBLIC_URL || '';
  const response = await fetch(
    `${baseUrl}/data/${languageInfo.file}`,
  );

  if (!response.ok) {
    throw new Error(`Could not load data: ${response.status}`);
  }

  const data = await response.json();
  dataCache[lang] = data;
  return data;
};

export const getReflection = async (lang, date) => {
  const data = await loadLanguageData(lang);
  return data.find((item) => item.date === date) || null;
};

The PUBLIC_URL prefix is important on GitHub Pages. A project site is served below a path such as /aa-daily-reflections-database, not necessarily from /. The prefix lets Create React App provide the correct base path during the build while keeping local development simple.

5. Verify the result without trusting the screen alone

Use the build output and the browser network panel as two separate checks.

First, confirm that the build created the copied files:

test -f build/data/daily_reflections_english.json
test -f build/data/daily_reflections_brazilian-portuguese.json

On PowerShell, use:

Test-Path build/data/daily_reflections_english.json
Test-Path build/data/daily_reflections_brazilian-portuguese.json

Then open the app and change the language. In the browser's Network panel, verify that the request changes to the corresponding file under data/. Change the date and confirm that the displayed record changes without a server-side API request.

Finally, refresh the page. The selected language and date should be restored because the context writes them to localStorage. If a JSON request returns 404, inspect the base path first. A missing PUBLIC_URL is a common static-hosting failure mode.

6. Publish the static build

The repository already includes a deploy script using the gh-pages package:

npm run deploy

Before using it, review the generated build directory and confirm that the repository's Pages configuration matches the branch and path you intend to publish. GitHub Pages is a static host here. It does not execute the React code on the server and it cannot provide private storage for reflection data or user preferences.

The project also generates a sitemap as part of its deployment-oriented script. Read scripts/generate-sitemap.js before adapting the domain or path for a fork. SEO metadata is only useful when its canonical URLs match the site that is actually being served.

Why this pattern works

This architecture matches the problem's access pattern:

The data is read-heavy and changes infrequently.
Each language can be downloaded independently.
Date selection is a local lookup over an already loaded array.
The UI needs no authentication or mutation endpoint.
The deployment artifact is ordinary HTML, JavaScript, CSS, and JSON.

The tradeoff is equally clear. Every browser that uses a language downloads that language's JSON file, and searching the full collection happens in the browser. If the corpus grows substantially, replace the array lookup with a generated index or a query service. Do not add a database server merely because the source data is also available as SQLite.

Limitations and security boundaries

The repository's MIT license covers the software compilation and examples, but its legal notice separately says that the original Alcoholics Anonymous materials remain copyrighted and that the compilation is unofficial. Do not treat the MIT notice as permission to republish the underlying literature without checking the rights for your use case. The project links to aa.org for official resources.

The portal also is not a medical service, a replacement for a recovery group, or a guarantee that a translation is official. Keep those boundaries visible if you fork it. Do not put private user notes into this static dataset: GitHub Pages publishes the generated files publicly.

FAQ

Do I need a backend?

Not for the included read-only portal. The browser fetches static JSON and performs the date lookup locally.

Why keep JSON, CSV, and SQLite?

They serve different consumers. JSON is convenient for browser and small scripts, CSV is useful for analysis, and SQLite is useful when a client needs indexed queries or joins.

Can I add another language?

Add a validated data file, register it in the language allowlist, copy it into public/data, and update the UI labels and documentation. Verify dates, encoding, attribution, and rights before publishing.

Takeaway

A multilingual daily-content portal can remain simple when the data contract is explicit. Start with a fixed language allowlist, cache one static file per language, persist only non-sensitive preferences, and make the deployment path part of the verification checklist.

What would you add first to this pattern: a generated search index, an accessibility test suite, or a small API for clients that cannot download the full language file?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. The repository links, commands, architecture notes, limitations, and security boundaries were checked against the current public repository and live site before publication.

Choose an ActiveAdmin Theme with a Reviewable Rails Checklist

Fernando Paladini — Wed, 04 Nov 2026 12:40:47 +0000

ActiveAdmin makes it quick to build an administrative interface in Rails, but the default interface is not always the right fit for a team. The harder part is often not writing CSS. It is choosing a theme without losing track of its source, compatibility, maintenance status, or the small Rails overrides that change behavior.

This tutorial shows a reviewable way to use activeadmin-themes: treat the repository as a curated starting point, inspect the linked theme source before installing anything, and keep any local Rails override explicit. The repository is a catalog, not a theme gem or a full Rails application.

TL;DR

Clone the catalog, choose a theme whose upstream repository you can inspect, record the exact dependency and asset instructions from that upstream project, and keep custom behavior in your Rails application. If you want to suppress ActiveAdmin's default CRUD flash messages, the catalog documents a small initializer patch. Verify that patch in your own test environment because the catalog does not test every ActiveAdmin and Rails combination.

Prerequisites

You need:

A Rails application that already uses ActiveAdmin.
Ruby and Bundler working for that application.
Git, so you can inspect the catalog and the upstream theme repositories.
A test or staging environment where you can exercise an ActiveAdmin create, update, and destroy action.

The catalog itself is a public MIT-licensed repository owned by Fernando Paladini. Its README is a Markdown list of themes and links. It does not install a theme, select one automatically, or guarantee that a linked project still supports your versions.

1. Inspect the catalog as evidence

Start by cloning the exact repository you are reviewing:

git clone https://github.com/paladini/activeadmin-themes.git
cd activeadmin-themes
git log -1 --format='%H %cI %s'

The README currently lists projects such as Active Admin Flat Skin, Active Admin Theme, Active Bootstrap Skin, ActiveMaterial, Arctic Admin, and Fuji Admin. Each entry links to an upstream repository or RubyGems package. That distinction matters: activeadmin-themes is a directory, so the linked project is the source of truth for installation commands and version support.

Before choosing a theme, open its upstream repository and check at least these items:

The installation instructions and dependency names.
The supported ActiveAdmin, Rails, Ruby, and asset pipeline versions.
The license and the latest meaningful activity.
Whether the project expects Sass, Tailwind, importmaps, Webpacker, or another asset path.
Whether the screenshots match the current code, rather than only an old release.

Do not copy a Gemfile line from the catalog because the catalog does not provide one. Copy it only from the upstream project's current documentation or release instructions, then pin and review it like any other dependency.

2. Keep the application change small

A theme should change the presentation layer. Application-specific behavior should stay in your application. For example, the catalog includes a documented initializer that suppresses ActiveAdmin's default CRUD flash messages:

# config/initializers/active_admin_disable_default_flash_messages.rb
Rails.application.config.to_prepare do
  ActiveAdmin::ResourceController.class_eval do
    private

    def set_flash_message(*)
      # Keep ActiveAdmin from overriding the flash hash.
    end
  end
end

This is a Ruby monkey patch. It is not a general security control, and it does not remove every notification your application might create. It changes a private controller method so it can become sensitive to ActiveAdmin upgrades. Keep the file small, add a comment explaining why it exists, and review it whenever ActiveAdmin changes.

If your application needs flash messages for accessibility or workflow feedback, do not apply this patch blindly. A better choice may be to replace the default message with an application-specific message, or to style the existing message through the chosen theme.

3. Verify the behavior in Rails

Restart the Rails server after adding an initializer. Then exercise one representative resource in a test or staging environment:

bin/rails db:prepare
bin/rails server

Open ActiveAdmin in a browser and test these paths:

Create a record and confirm the result is understandable without relying on the default CRUD flash.
Update a record and confirm validation errors remain visible.
Destroy a record and confirm the redirect and authorization behavior are unchanged.
Check a narrow viewport and keyboard navigation after the theme assets load.

The expected result is not simply “the page looks different.” You want a documented theme choice, a reproducible dependency change, and application behavior that remains understandable after the visual change. If you cannot explain where an asset came from or which version supports your ActiveAdmin setup, the review is incomplete.

For a quick repository-level check, search the catalog for the documented override and inspect the Markdown around it:

rg -n -C 8 "set_flash_message|ActiveAdmin::ResourceController" README.md

That command verifies the current catalog contains the example. It does not prove that your Rails application loads the initializer correctly. Only your application's test or staging run can do that.

Why this workflow works

The catalog separates discovery from adoption. Discovery is cheap: you can compare several themes in one place. Adoption is deliberately slower: the upstream project must provide the dependency contract, asset instructions, and compatibility evidence.

That separation also makes reviews easier. A pull request can show the selected upstream URL, the dependency diff, the asset configuration, and the screenshots or browser checks that justify the choice. Future maintainers do not have to guess whether a line came from the catalog, the theme author, or a local workaround.

The same principle applies to the flash-message patch. It is useful because it is small and visible, but it is risky because it reaches into a controller implementation detail. Keeping it as a named initializer makes that risk searchable.

Failure modes and honest limits

The theme is listed but no longer works

The catalog is not a compatibility matrix. A linked repository can be archived, renamed, or designed for an older ActiveAdmin release. Treat every entry as a lead and re-check the upstream source before adding a dependency.

The asset pipeline is different

A theme built for Sass is not automatically compatible with a Tailwind-based ActiveAdmin application, and a theme's screenshots do not tell you how it is loaded. Follow the upstream instructions for your asset system and verify the compiled output in a real environment.

The patch hides useful feedback

Suppressing default CRUD messages can make an admin workflow harder to understand. Preserve validation errors, authorization failures, and any feedback your operators need. Prefer a replacement message when the workflow requires confirmation.

A private API changes

ActiveAdmin::ResourceController and set_flash_message are implementation details for this purpose. A future ActiveAdmin release can change them. Pin versions according to your application's policy, run the relevant tests, and remove the patch if the upstream behavior changes.

The repository contains old examples

The catalog is a curated list, not a release artifact. Its README can remain useful while some linked projects age. Record the date and commit you reviewed in your project decision log.

FAQ

Does activeadmin-themes install a theme?

No. It catalogs themes and links to their upstream projects. Installation belongs to the selected project's documentation.

Is the flash-message initializer required?

No. It is an optional documented example. Use it only when your application has a clear reason to change the default behavior.

Can I use a listed theme in production?

The catalog does not make that decision for you. Check the upstream license, maintenance, compatibility, security posture, and your own regression checks.

What should I contribute back?

The README asks maintainers to submit a pull request or open an issue when they find a new ActiveAdmin theme. Include the theme's canonical upstream link and enough evidence for another maintainer to review it.

Takeaway

Use activeadmin-themes as a reviewable index, not as a dependency. Choose an upstream project, verify its contract, keep local Rails overrides explicit, and test the admin workflows that your operators actually use.

Have you found a reliable way to evaluate ActiveAdmin theme compatibility across Rails upgrades without turning your application into a screenshot-only test suite?

AI assistance disclosure

AI assistance was used to organize this tutorial and check the Markdown structure. Repository facts, commands, limitations, and the documented Ruby example were checked against the public project sources linked above; no claim of a full Rails application run is made here.

Edit Currículo Lattes XML Safely with TypeScript and lattes-toolkit

Fernando Paladini — Tue, 03 Nov 2026 12:32:40 +0000

If you maintain a Currículo Lattes, a small correction can become a fragile manual task: export the file, find the right XML element, edit it without breaking the document, and remember what changed before importing it again.

This tutorial shows a safer local workflow with lattes-toolkit. We will use the stable v2.4.0 release to read an exported XML file, change one typed field, preserve a backup, and verify the result before the human-controlled import step.

TL;DR

@paladini/lattes-toolkit is a TypeScript library and CLI for working with XML that you already have. It does not log in to Plataforma Lattes, download a curriculum, or click Import XML for you. That boundary is useful: the file stays local, and the final review remains explicit.

The core workflow is:

Export your XML from Plataforma Lattes.
Parse and inspect it locally.
Apply a narrow change.
Confirm the generated XML and keep the automatic backup.
Review and import the file manually.

The CNPq description of Plataforma Lattes explains the platform's role in Brazilian research information. The toolkit is an independent project and is not affiliated with CNPq.

Prerequisites

You need:

Node.js 18 or later.
An XML or ZIP export that you are allowed to edit.
A terminal and a text editor.
A separate copy of the original file before experimenting.

This tutorial is pinned to @paladini/lattes-toolkit@2.4.0, released from the repository's v2.4.0 tag. Pinning the version makes the commands reproducible even if npm's latest dist-tag moves later.

Install the pinned CLI

You can install the package in a project or invoke its CLI with npx:

npm install @paladini/lattes-toolkit@2.4.0
npx @paladini/lattes-toolkit@2.4.0 --help

The package declares Node.js >=18.0.0, uses the MIT license, and exposes the lattes-toolkit command. The help output is the quickest way to check that the expected CLI is available:

Usage:
  lattes-toolkit init [dir]
  lattes-toolkit parse <file.xml|zip> [--json|--summary]
  lattes-toolkit get <file> <path>
  lattes-toolkit set <file> <path> <value>
  lattes-toolkit serialize <file.json> -o <out.xml>
  lattes-toolkit backup list [dir]
  lattes-toolkit restore [--last|<backup-id>] [dir]
  lattes-toolkit validate <file.xml> [--dtd [file.dtd]]
  lattes-toolkit patch <file.xml> <patches.json>

Inspect an exported curriculum

Export your curriculum through the normal Plataforma Lattes interface and save it as curriculo.xml. Do not place a real curriculum in a public repository or issue. It contains personal data.

Start with a summary:

npx lattes-toolkit@2.4.0 parse curriculo.xml

If you need a particular field, use dot and bracket notation. For example, this reads the first journal article title:

npx lattes-toolkit@2.4.0 get curriculo.xml bibliographicProduction.journalArticles[0].title

The field names come from the toolkit's typed model, not from a guess about raw XML capitalization. The repository documents CLI commands and typed field coverage.

Make one narrow edit

Suppose the summary needs a correction. Use set with the exact path and value:

npx lattes-toolkit@2.4.0 set curriculo.xml identification.summary "A corrected professional summary."

The command serializes the XML back to the same path. When that destination already exists, the toolkit creates a snapshot under .lattes-backup/ before overwriting it. The backup documentation describes the manifest, SHA-256 value, retention behavior, and restore commands.

List the available snapshots:

npx lattes-toolkit@2.4.0 backup list

If the result is not what you expected, restore the latest snapshot before trying again:

npx lattes-toolkit@2.4.0 restore --last

For multiple edits, prefer patch with an allowlist rather than giving an automated process unrestricted access to the document:

{
  "allowlist": ["identification.summary"],
  "patches": [
    {
      "path": "identification.summary",
      "value": "A corrected professional summary."
    }
  ]
}

Save that as patches.json, then run:

npx lattes-toolkit@2.4.0 patch curriculo.xml patches.json

An allowlist is a practical safety boundary. It makes the intended edit reviewable and prevents a broad instruction from silently changing unrelated sections.

Verify before import

Read the edited field again:

npx lattes-toolkit@2.4.0 get curriculo.xml identification.summary

The package also includes an XSD-based validation command. It uses xmllint when that tool is available in your environment:

npx lattes-toolkit@2.4.0 validate curriculo.xml

Validation is not a promise that the Plataforma Lattes interface will accept every file. The project's documentation explicitly describes XSD and optional local DTD checks as environment-dependent, and says that schema validation does not guarantee platform acceptance.

For a programmatic workflow, the same boundaries are available in TypeScript:

import { readFileSync } from "node:fs";
import {
  applyCurriculumPatches,
  readCurriculum,
  writeCurriculum,
} from "@paladini/lattes-toolkit";

const curriculum = await readCurriculum(
  readFileSync("./curriculo.xml"),
);

applyCurriculumPatches(
  curriculum,
  [{ path: "identification.summary", value: "A corrected professional summary." }],
  { allowlist: ["identification.summary"] },
);

await writeCurriculum(curriculum, "./curriculo.xml");

After writing, parse the file again and inspect the changed field. Then open the XML in the Plataforma Lattes interface, review it, and perform the import yourself. The toolkit does not automate login or submission.

Why this workflow is safer

The library models supported fields as typed data, while retaining unmapped document content during the XML round trip. That is more deliberate than using a regular expression over XML text. The set command is useful for one field, while patch makes a batch change auditable through a JSON file.

Automatic snapshots address a different risk: editing the right field but disliking the result. The backup is local and should be excluded from Git with .lattes-backup/ in .gitignore.

The release history also matters. Version 2.0.0 introduced breaking model and serialization changes aligned with the repository's versioned XSD. Version 2.4.0 added typed technical-production fields. Pinning a release avoids accidentally mixing this tutorial with a future CLI or model change.

Failure modes and limits

The field path is wrong

A path that is not present in the typed model will not produce the intended update. Start with parse, consult the field coverage documentation, and make one small change at a time.

`xmllint` is unavailable

The validation command can report that validation was skipped when the required executable or local DTD is missing. Treat that as a missing verification step, not as proof that the file is valid.

The platform rejects the import

The toolkit cannot guarantee acceptance by Plataforma Lattes. Keep the original export, inspect the backup, and use the platform's own error message and documentation. Do not use the library to bypass a CAPTCHA, terms of use, or a required manual review.

Personal data leaks

Curricula contain personally identifiable information. Work on local copies, do not upload real XML to chat or public issue trackers, and use synthetic or anonymized fixtures for tests. The project explicitly says it does not download a curriculum from the public web or query a CPF.

FAQ

Does this package edit the online curriculum directly?

No. It edits an XML or ZIP file that you already have. Export and import remain manual.

Can I use it with an AI agent?

Yes, but give the agent a narrow allowlist, require a re-parse after writing, and keep the import step under human control. The repository has an AI-agent integration guide.

Does `validate` prove the import will work?

No. It can check against the packaged XSD when xmllint is available. Platform acceptance has additional behavior outside the toolkit's control.

Is this an official CNPq package?

No. It is an independent MIT-licensed project and states that it is not affiliated with CNPq.

Takeaway

Treat a Currículo Lattes export as a local, reviewable data file: pin the tool version, change only named fields, keep automatic snapshots, validate when possible, and import manually after checking the generated XML. That gives you repeatable edits without pretending that a local parser can replace the platform's own review and submission controls.

Have you found a useful field-level Lattes workflow that benefits from an allowlist and a generated backup?

AI assistance disclosure: I used AI assistance to organize and draft this tutorial. The commands, version details, project behavior, limitations, and links were checked against the paladini/lattes-toolkit v2.4.0 sources and a pinned CLI smoke test before publication.

Find Missing Loading and Error States in Next.js with unhappypath

Fernando Paladini — Sun, 01 Nov 2026 12:38:09 +0000

AI coding tools are good at making the successful path visible quickly. They can produce a page that loads data, accepts a form, and responds to a button click while leaving the slower, empty, failed, or repeated paths unfinished.

That gap is easy to miss in a screenshot. It is also expensive to find manually across every route and component. unhappypath is a small open-source CLI that scans source code for several of these missing UI states. It does not run a browser or call an LLM. It produces a repeatable score and findings that point to files, lines, and rule IDs.

This tutorial uses the current main source at commit 0827ee0. The repository currently reports version 0.1.0 in package.json, requires Node.js 20 or newer, and is licensed under MIT. There is no public release or tag, so the commands below describe the current repository state rather than a stable release.

TL;DR

Clone the repository, install its dependencies, build it, and scan a project directory:

git clone https://github.com/paladini/unhappypath.git
cd unhappypath
npm ci
npm run build
node dist/cli.js /path/to/your-next-app

The result includes a score from 0 to 100, four dimension scores, and findings such as RTE-01 for a missing loading boundary or QRY-02 for a query without visible error handling.

Prerequisites

You need Git, Node.js 20 or newer, npm, and a local Next.js or React project to inspect. The scanner reads source files from disk. It does not need a running development server, a database, API credentials, or network access after dependencies are installed.

The project depends on TypeScript for its build and uses Node's built-in test runner. Its package metadata declares MIT licensing and the CLI entry point as dist/cli.js.

Build the scanner from source

The repository documents npm ci followed by npm run build. Run those commands from the repository root:

npm ci
npm run build

After the build, the executable is available at dist/cli.js. The package also exposes an unhappypath binary when installed as a package, but building from source makes the inspected commit explicit.

Run the project's tests before using it in a workflow:

npm test

In the current checkout, this completed successfully with 18 tests. The test command builds first and then executes the compiled tests, so a successful result covers both the TypeScript compilation and the repository's fixture contracts.

Scan a project

Point the CLI at the directory that contains the application source:

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

The path is positional. If you omit it, the CLI uses the current directory. For a machine-readable report, add --json; for a Markdown report, use --markdown. To make the command fail when the score is below a threshold, use --min-score:

node dist/cli.js . --json --out unhappypath-report.json --min-score 75

The CLI documents exit code 0 for a successful scan, 1 when --min-score is not met, and 2 for a usage error. A threshold is a policy choice, not a claim that the application is production-ready. The scanner only checks the signals implemented by its rules.

Use the built-in fixtures to understand the output

The repository includes a deliberately incomplete project and a project with the expected boundaries. Run both demos:

npm run demo:broken
npm run demo:good

The broken fixture currently reports 38/100 and 14 findings. It includes missing route boundaries, a query without loading, error, or empty handling, a form without pending feedback, a fetch effect without loading and error state, and an asynchronous click without a disabled or pending state.

The good fixture reports 100/100 and zero findings. That is useful for checking the command and output format, but it is not evidence that an arbitrary application has complete UX coverage. The fixture is intentionally shaped around the scanner's current heuristics.

Read findings as repair guidance

The rule IDs are stable within the repository's documented ups-v1 reference. Route checks include:

RTE-01: a route page has no loading boundary in its segment or ancestors.
RTE-02: a route has no not-found.tsx boundary in its segment or ancestors.
RTE-03: a route has no error.tsx boundary in its segment or ancestors.
RTE-04: the application has no root global-error.tsx.

For data and interaction code, query rules look for loading, error, and empty branches. Mutation rules look for pending feedback and empty catches. Form rules look for submitting or disabled behavior. A finding includes a file and line so you can inspect the source rather than guessing what the scanner saw.

The repository's recommended repair order is routes, queries, mutations, and forms. For example, a Next.js route can inherit an app/loading.tsx, while a query component should expose loading, error, and empty states near the query result. A scanner finding is a prompt to review the code, not an automatic patch.

Add a conservative CI gate

The README documents a GitHub Actions composite action as well as a direct npx example. A minimal workflow step is:

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

The current repository's action.yml invokes npx --yes unhappypath@0.1.0 and accepts path, min-score, and format inputs. If you use that action, review the pinned version and its source before trusting it in a production workflow. The repository also documents the composite action form:

- uses: paladini/unhappypath@v1
  with:
    path: .
    min-score: "75"

The two examples have different versioning behavior. The direct command from the README uses the package name without a version, while the composite action currently calls 0.1.0. Check the project's release status before adopting either form. At the time of this tutorial, no GitHub release or tag was published.

Why this is useful, and where it stops

The scanner combines two kinds of static checks. A route scanner inspects Next.js App Router files such as page.tsx, loading.tsx, error.tsx, and not-found.tsx. A code scanner uses the TypeScript AST to inspect patterns such as query hooks, fetch calls inside effects, asynchronous click handlers, and forms.

That design makes the result deterministic and local. The same source tree can produce the same report without model tokens or external service availability. It also means the tool cannot prove runtime behavior. It does not run a browser, simulate a slow network or a server error, judge the quality of copy, or replace end-to-end tests. Its documented blind spots include deeply nested child-component handling and limited analysis of asynchronous Server Components.

Security boundaries matter too. The scanner reads files from the path you give it and writes reports or badges only when you request those outputs. It does not claim to validate authorization, input handling, secrets, dependencies, or server-side security. Keep those checks in their appropriate tools and tests.

FAQ

Does it support every React framework?

Not according to the current documentation. Its route rules target the Next.js App Router, while its code rules inspect selected TypeScript and React patterns. Vue, Nuxt, SvelteKit, and Remix route conventions are listed as future work.

Does a score of 100 mean the UI is production-ready?

No. It means the current rules found no missing signals in the scanned source. A score does not evaluate visual design, copy, runtime failures, accessibility quality, performance, or business behavior.

Can I use it without installing the repository?

The README documents npx unhappypath /path/to/your-next-app as the future npm option. The current repository also provides a source checkout path that works today. Verify package publication and version availability before depending on an unpinned command.

Takeaway

unhappypath is most useful as an early, deterministic review pass after an AI-assisted implementation. Build it from a known commit, scan the application, inspect each finding, and combine the result with runtime tests and human review. Treat the score as a prioritized checklist rather than a proof of readiness.

What is the most valuable unhappy-path check for your team: route boundaries, data states, mutation feedback, or form submission behavior?

Disclosure: This article was prepared with AI assistance. The repository documentation, package metadata, current commit, public GitHub metadata, and local commands described here were checked before publication.

Add Local Developer Utilities to Any MCP Assistant with DevUtils

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

AI assistants are useful at translating intent into actions, but small developer utilities are an easy place for an agent to guess. A guessed hash, a malformed JSON transformation, or a misunderstood JWT timestamp can waste more time than the original task.

DevUtils MCP Server provides a local set of 36 developer utilities through the Model Context Protocol (MCP). The server exposes hashing, encoding, ID generation, JWT inspection, JSON formatting, network calculations, and text utilities over standard input and output. The operations run locally and the project documents no external API dependency.

This tutorial installs the stable v1.1.0 release, connects it to an MCP client, verifies the transport with a real initialize request, and explains where the tool is useful and where it is not.

TL;DR

Run the server with Node.js 18 or newer:

npx -y devutils-mcp-server@1.1.0

Then add the same command to your MCP client configuration:

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

After restarting the client, it can call tools such as hash_sha256, json_validate, generate_uuid, cidr_calculate, and text_stats.

Prerequisites

You need:

Node.js 18 or newer. The project recommends Node.js 22 for its current development environment.
An MCP-compatible client such as Claude Desktop, Cursor, VS Code Copilot, or Windsurf.
Network access only for the first npx package download. The server itself uses stdio and is documented as having no external API dependency.

The commands below target the published v1.1.0 release. The repository default branch currently contains 1.1.1, so pinning the package version makes this walkthrough reproducible against the stable release that was checked.

Install and connect the server

The simplest path does not install a global package. npx downloads the requested package version and starts its executable:

npx -y devutils-mcp-server@1.1.0

An MCP server using stdio is not a traditional web service. It waits for JSON-RPC messages on standard input and writes protocol responses to standard output. That is why the client configuration names a command and arguments rather than a URL.

For Claude Desktop on Windows, the documented configuration file is %APPDATA%\\Claude\\claude_desktop_config.json. For a workspace-specific VS Code setup, use .vscode/mcp.json with the VS Code servers shape:

{
  "servers": {
    "devutils": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "devutils-mcp-server@1.1.0"]
    }
  }
}

Use the configuration shape required by your client. Claude Desktop, Cursor, and Windsurf use an mcpServers object in the project documentation, while VS Code uses servers and includes type: "stdio".

Verify the transport before using tools

You can verify the minimal path without opening a client. Send an MCP initialize request to the package:

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

The expected result is a JSON-RPC response containing the negotiated protocol version and server information. The server may also write a short status message to stderr. That status line is separate from the JSON-RPC response and should not be parsed as a tool result.

The release smoke test returned this server identity:

{
  "name": "devutils-mcp-server",
  "version": "1.1.0"
}

If the command cannot find npx, check node -v and npm -v in the same environment used by your MCP client. GUI clients can inherit a different PATH from your interactive shell.

Use the tools for bounded operations

Once connected, ask the assistant for a small, inspectable operation. For example:

Use the DevUtils hash_sha256 tool on the exact string hello and return only the hexadecimal digest.

The server registers tools in eight groups. The release README lists six hash tools, eight encoding tools, four generators, two JWT tools, three formatters, five converters, two network tools, and six text tools. Names follow a predictable <domain>_<operation> pattern.

For structured data, a useful request is:

Use json_validate on this JSON and explain the error location if it is invalid: { "enabled": true, }

For network data, use a non-sensitive example:

Use cidr_calculate for 192.168.10.0/24 and show the network, broadcast, host range, and host count.

These examples are intentionally bounded. The model chooses an explicit tool and supplies typed arguments, while the server performs the utility operation and returns text. You still need to inspect the result when it matters.

Why the MCP boundary helps

The value is not that a local library becomes faster through MCP. Native libraries are usually the right choice inside application code. The value is that an MCP client can call a consistent, typed operation during a multi-step conversation without inventing an implementation.

DevUtils uses the official TypeScript MCP SDK, Zod schemas for tool inputs, and stdio transport. The source registers each tool category with an McpServer before connecting a StdioServerTransport. That keeps the boundary explicit: the assistant can request a named operation, but it does not receive arbitrary code execution through this server.

The repository also keeps the package small enough to understand. The source is organized under src/tools/ by category, including hash.ts, formatters.ts, network.ts, and text.ts. That structure makes the project useful as a reference when you want to learn how a TypeScript MCP server wires schemas and handlers together.

Important limitations and security boundaries

DevUtils is a utility server, not a general security oracle.

The jwt_decode and jwt_validate tool descriptions explicitly say that they do not verify a JWT cryptographic signature. Decoding a token can help inspect its header and payload, but it does not prove that the token was issued by a trusted authority. Never treat a decoded payload as authenticated.

Hashing tools also have different purposes. MD5 and SHA-1 are available for compatibility and checksums, not for password storage. For passwords, use a dedicated password hashing scheme and an appropriate work factor. DevUtils includes bcrypt operations, but its presence does not remove the need to manage credentials, secrets, and authentication policy correctly.

The server runs locally through stdio and the security policy says it does not expose HTTP endpoints or send user data to external services. That is a useful boundary, not a universal privacy guarantee. The MCP client still receives the inputs you give it, npx still downloads a package before first use, and your machine still controls the process environment. Review the package, lock down client permissions, and avoid sending secrets in casual prompts.

The project is also not the best choice for every workload. If application code needs a hash, JSON parser, or CIDR calculation, use the native library directly. MCP adds a process and protocol boundary, which is valuable for agent workflows but unnecessary for a tight application loop.

FAQ

Does the server need an API key?

No API key is required by the documented package configuration. The server is started locally with Node.js and uses stdio.

Does it work with every AI assistant?

It works with MCP-compatible clients. The README documents Claude Desktop, Cursor, VS Code Copilot, Windsurf, Docker, and other MCP clients. A client without MCP support cannot use this server through the documented path.

Should I use the unpinned `npx devutils-mcp-server` command?

You can follow the README's short command, but a pinned version is better for a reproducible setup. Recheck the current release before upgrading.

Is JWT validation cryptographic verification?

No. The documented jwt_validate operation checks structure, JSON, expiration, and signature presence. It does not verify the signature against a key.

Takeaway

DevUtils MCP Server is a practical way to give an MCP-compatible assistant a small, local toolbox with explicit names and typed inputs. Start with the pinned v1.1.0 command, verify the initialize response, and then try one bounded operation such as JSON validation or SHA-256 hashing.

Have you found a developer utility that an AI assistant repeatedly gets wrong and that would benefit from a typed MCP tool?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, version details, configuration examples, and security boundaries were checked against the project's public documentation, source, release metadata, and a live initialize smoke test.

Build a Test-Gated Manifest V3 Extension for Safe X Tab Automation

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

Automating actions in a social timeline is easy to start and surprisingly hard to bound. A browser extension can click the wrong control, run while you are away from the tab, request more permissions than it needs, or hide its failure mode behind a vague counter.

This tutorial uses X Likes Automator, a small open-source Manifest V3 extension, to show a more reviewable path. You will install the stable v1.1.0 release, inspect the permission boundary, run the repository's 171-test suite, and configure a deliberately conservative first session.

The goal is not to promise safe or compliant automation. The project warns that automated likes can conflict with X rules and may lead to rate limits, restrictions, or suspension. Treat the extension as an educational, personal-use example and stop if X shows an automation warning.

What you will build

You will load an unpacked browser extension into a Chromium browser and use it only in an X tab where you are already signed in. The extension reads visible posts, selects an eligible Like control, and pauses when the tab or window is not active.

The important design choice is the narrow surface: the extension is not a login client and does not use an X API token. Its manifest requests storage plus host access for https://x.com/* and https://twitter.com/*. The repository's security tests also assert that cookies, passwords, session tokens, and unrelated sites are not collected.

Prerequisites

Chrome, Brave, or Microsoft Edge with Manifest V3 support.
A normal browser tab already open at X, with an account you control already signed in.
Node.js 20 or newer if you want to run the tests. Node is not required to run the unpacked extension.
A clone or the official v1.1.0 release archive.

Do not paste credentials into the repository or into the extension. Do not use a browser profile that contains accounts you are not authorized to operate.

1. Verify the release locally

Clone the exact stable tag instead of relying on the moving default branch:

git clone --branch v1.1.0 --depth 1 https://github.com/paladini/x-likes-automator.git
cd x-likes-automator

The tag is the reproducibility anchor for this tutorial. The README and release page identify v1.1.0, while the license file identifies the project as MIT.

Run the included checks:

npm test

The release currently reports 171 passing tests covering the manifest, permissions, settings, visible-page behavior, pause and resume rules, refusal list, localization, documentation, and policy engine. A green run does not prove that X accepts automated activity. It only checks the tagged project behavior.

2. Load the extension without a build step

Open the extensions page for your browser. In Chrome, the documented address is chrome://extensions; the equivalent pages are brave://extensions and edge://extensions.

Enable Developer mode.
Click Load unpacked.
Select the cloned x-likes-automator directory.
Confirm that the selected directory contains manifest.json at its top level.

The repository deliberately has no bundling step. Loading the source directory makes the reviewed JavaScript, manifest, popup, icons, and tests visible. If the browser reports a manifest error, stop and inspect the selected directory instead of downloading a random replacement archive.

Pin X Likes Automator in the browser toolbar, then open https://x.com/home in a regular tab. The extension does not open a new window or perform a login flow.

3. Configure a conservative first session

The popup is localized in Brazilian Portuguese. The setting names below are the behavior documented by the release:

Setting	`v1.1.0` behavior
Interval	Integer from 1 to 60 seconds; default 5 seconds
Interval jitter	A 5-second setting chooses a delay from 4.25 to 5 seconds
Optional cap	1 to 1,000,000 when enabled; default stored cap is 100
Original post in a reply thread	Enabled by default
Plain repost	Enabled by default, but can be turned off

For a first review, set the interval to 60 seconds, enable a cap such as 5, and turn off Repostar também. This keeps the session focused on the Like path and gives you a short, observable run. The cap is a control for your account activity, not a guarantee of compliance.

Press Iniciar while the active tab is an X home timeline, profile, search result, or single-post thread. If the active tab is another site, the project refuses to start.

4. Observe the policy boundary

The extension separates decisions from DOM operations. lib/policy.js is a pure decision engine that validates settings, classifies the current X surface, chooses the next eligible post, and decides whether to like, scroll, wait, pause, or stop. content/content.js adapts those decisions to the page.

That separation gives you useful review points. The extension should pause when the document is hidden or the window loses focus. It should skip a post that is already liked, remember a post within the current session, and refuse unsupported pages such as messages, settings, notifications, and compose screens.

The project also keeps an explicit refusal list. It does not click reply, quote, follow, direct message, login, or cookie controls. When the optional repost behavior is enabled, it only targets the plain repost menu item and never opens a composer.

If X displays an unusual-activity notice, the documented behavior is to wait 60 seconds and resume. The extension does not attempt to bypass that protection. You should still stop the session if the notice repeats or if the account's activity looks unexpected.

5. Verify the result and stop cleanly

During a small capped run, check the popup counter against the visible page. Switch away from the X tab and confirm that the status changes to paused. Return to the tab and confirm that the same session count resumes. Then click Parar before investigating anything else.

The repository documents a five-minute page reload cycle that preserves the session count through browser storage. A browser restart clears the volatile run state, so starting again requires an explicit button press. These details matter because a persistent background worker would have a different risk profile.

After stopping, inspect the browser's extension details and the repository's manifest.json. The expected permission shape is small:

{
  "permissions": ["storage"],
  "host_permissions": ["https://x.com/*", "https://twitter.com/*"]
}

This snippet is a review aid, not a complete manifest. Compare it with the actual release file rather than replacing the file with a hand-written version.

Failure modes worth checking

The popup says the tab is unsupported. Navigate to the X home timeline, a profile, a search result, or a thread. The extension intentionally ignores messages, notifications, settings, explore, compose, and non-X pages.

The session stays paused. Make the X tab visible and focus the browser window. The pause is presence-based by design.

The session does not start after installation. Reload the X tab and press Iniciar again. A tab that existed before installation may not yet have the content script.

The browser shows an automation warning. Do not increase the rate or try to evade the warning. Stop the session, review the account impact, and consult X's current rules.

The test suite fails. Do not treat a partial result as release validation. Check the Node version, rerun npm test from the tagged checkout, and compare the local files with the official release.

Security and privacy boundaries

The extension's narrow permissions reduce exposure, but they do not remove the central risk: it acts on a signed-in social account. The project cannot guarantee that a selector will remain correct as X changes its interface, and it cannot guarantee that automated activity is allowed for your account.

Review the security policy before reporting a vulnerability. Keep the account logged in only in a profile you control, use a small cap, keep the interval conservative, and remove the unpacked extension when you finish evaluating it.

FAQ

Does it need an X API key?

No. The documented design uses the open X tab and does not request an API token or credentials.

Does it run on every website?

No. The manifest host permissions and content-script matches are limited to X and Twitter origins.

Is a passing test suite a safety guarantee?

No. It verifies repository behavior at the checked-out release. It cannot predict policy enforcement, account restrictions, or future changes to X's DOM.

Can I make it run unattended?

The project is designed around an active, visible tab and pauses when the tab is inactive. Do not treat its reload behavior as permission to leave account automation unattended.

Takeaway

The useful lesson in X Likes Automator is not that social activity can be automated. It is that a browser extension becomes easier to review when its release is pinned, permissions are explicit, decisions are tested, unsupported actions are refused, and stopping behavior is visible.

If you try the tagged release, keep the first session small and verify each state transition yourself. Which boundary would you want to see tested before trusting a browser extension that acts on a signed-in account?

Disclosure: AI assistance was used to organize and edit this tutorial. The repository behavior, release metadata, documentation, license, configuration, and test result described here were checked against the public v1.1.0 sources.

DEV Community: Fernando Paladini

Build an Evidence-Friendly Bitcoin Timeline with Static HTML and TimelineJS

Build an Evidence-Friendly Bitcoin Timeline with Static HTML and TimelineJS

TL;DR

Prerequisites

1. Run the existing timeline

2. Understand the data boundary

3. Connect the data to TimelineJS

4. Keep a crawlable fallback

5. Add metadata without hiding the content

6. Verify changes reproducibly

Why this structure works

Failure modes and limitations

FAQ

Does this need a database?

Is it fully offline?

Is this an investment tool?

Can I add my own milestones?

Takeaway

Build a Reproducible POSCOMP Study Library from an Open Source Archive

TL;DR

Prerequisites

1. Clone a known revision

2. Read the index before opening PDFs

3. Build a local inventory

4. Check that the PDFs are readable

5. Turn the archive into a study loop

Expected result

Why the Git workflow helps

Failure modes and limitations

FAQ

Is this the official POSCOMP website?

Do I need to install a programming language?

Should I edit the cloned repository with my answers?

Can I rely on the newest year shown in the README?

Takeaway

Install a Local MCP Utility Plugin in Cursor with DevUtils

TL;DR

Prerequisites

Install it in Cursor

What Cursor is launching

Verify the connection without guessing

Useful operations to try

Why the local boundary matters

Failure modes and limits

The server does not appear in Cursor

npx cannot download the package

The assistant answers without using the tool

You need application-level performance

You need a security guarantee

FAQ

Does the plugin require an API key?

Can I use it without Cursor?

Is the plugin the same as the server?

Are JWTs sent to a cloud service?

Takeaway

Give Your Coding Agent Semantic Code Navigation with Locus MCP

TL;DR

Prerequisites

1. Install and initialize Locus

2. Verify the local boundary

3. Add Locus to your agent host

What the six tools change

Reproducible verification

Failure modes and limitations

The agent sees no symbols

The server is still starting

Text search is still necessary

Security and trust boundaries

FAQ

Does Locus edit code?

Which editors are supported?

Do I need every language server?

Is this a full IDE inside MCP?

Takeaway

Install Reviewable Agent Skills with the Tech Leads Club CLI

TL;DR

Prerequisites

Install one skill locally

Verify the result

`npx` cannot download the package

Why pin `1.4.10` instead of using `npx` without a version?

`xmllint` is unavailable

Does `validate` prove the import will work?