paladini

Choose an ActiveAdmin Theme with a Reviewable Rails Checklist --- title: "Choose an ActiveAdmin Theme with a Reviewable Rails Checklist" published: true description: "Use activeadmin-themes to compare Rails admin themes, apply a documented flash-message patch, and verify the limits before shipping." tags: ruby, rails, tutorial, activeadmin --- 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: 1. The installation instructions and dependency names. 2. The supported ActiveAdmin, Rails, Ruby, and asset pipeline versions. 3. The license and the latest meaningful activity. 4. Whether the project expects Sass, Tailwind, importmaps, Webpacker, or another asset path. 5. 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.

Learn Your Writing Style Locally with AuthorStyle and Python --- title: "Learn Your Writing Style Locally with AuthorStyle and Python" published: true description: "Build an evidence-backed writing-style profile from your own corpus with AuthorStyle, then verify the local workflow and its privacy boundaries." tags: python, cli, tutorial, stylometry --- If you want an AI system to write in a style that feels like yours, the first problem is not a clever prompt. It is deciding what "your style" means and how to test whether a generated passage resembles it. AuthorStyle takes a research-oriented approach to that problem. It is a Python command-line tool that learns recurring patterns from a local corpus, records evidence for its style profile, and evaluates generated candidates against held-out writing. The project is alpha software, so the useful outcome is an inspectable experiment, not a promise of a perfect voice clone. TL;DR Install AuthorStyle 0.2.1, create a profile, ingest a directory of Markdown or other supported documents, and analyze it locally. The minimal path produces corpus statistics and a Style Card with measurable observations such as sentence rhythm, paragraph rhythm, lexical diversity, and punctuation rates. This tutorial uses the repository's English fixtures so the workflow is reproducible without supplying private writing. Replace that directory with your own corpus only after reviewing the privacy mode and data-handling boundaries. Prerequisites You need: - Python 3.11 or newer. - Git. - A local corpus you are allowed to process, or the repository's fixture corpus. - A terminal. The commands below include a Windows PowerShell path and a POSIX shell path where activation differs. AuthorStyle 0.2.1 is published in the repository's v0.2.1 tag. The package declares the MIT license and supports Windows, macOS, and Linux through Python's normal environment model. The project is marked alpha in its package metadata, which matters when deciding how much to rely on generated output. Install the tested version Clone the repository and create an isolated virtual environment. Pinning the tag keeps the example aligned with the documented release instead of silently following unreleased main changes. git clone --branch v0.2.1 https://github.com/paladini/authorstyle.git cd authorstyle python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" On Windows PowerShell, activate the environment with: git clone --branch v0.2.1 https://github.com/paladini/authorstyle.git Set-Location authorstyle py -3 -m venv .venv .venv\Scripts\Activate.ps1 python -m pip install -e ".[dev]" The development extra installs the test tools in addition to the runtime dependencies. The optional embeddings and nlp extras are separate; the basic workflow does not require them. Build a local profile Start with a profile name and ingest the fixture corpus. A profile is stored below ~/.authorstyle/profiles/<profile_id>/ according to the README. authorstyle init demo authorstyle ingest demo ./fixtures/corpus/en authorstyle corpus stats demo authorstyle analyze demo authorstyle profile show demo On Windows PowerShell, the same commands use the installed console script: authorstyle init demo authorstyle ingest demo .\fixtures\corpus\en authorstyle corpus stats demo authorstyle analyze demo authorstyle profile show demo The repository's current fixtures produced three documents and seven chunks during verification. The exact counts will differ for your corpus. corpus stats reports documents, chunks, words, canonical families, and modes, while profile show summarizes the resulting global profile. The important detail is the order. Ingestion normalizes and records source material, analysis builds the profile and Style Card, and the display commands let you inspect what was actually learned. You are not handing the tool a paragraph and asking it to guess a personality in one step. What the Style Card measures AuthorStyle combines explicit stylometry with pluggable style and semantic encoders. The documented methodology separates the two concepts: style describes how text is written, while semantic signals describe what it is about. The current methodology lists sentence and paragraph rhythm, punctuation rates, lexical diversity, Markdown structure, and technical prose or code ratios among the explicit features. A generated Style Card can contain observations like these: ## Sentence rhythm Typical sentences center around 18.0 words (q25=12.0, q75=24.0). Evidence metrics: median_sentence_length ## Punctuation and typography Notable punctuation rates: comma=4.20/100w, question=1.10/100w Evidence metrics: punct_comma_per_100_words, punct_question_per_100_words Those numbers are evidence about the supplied corpus, not universal facts about the author. If the corpus contains only API documentation, the profile may reflect that document type as much as the writer's broader voice. Add a real corpus safely AuthorStyle supports .md, .txt, .html, and .docx files. Markdown can include YAML front matter with fields such as title, date, language, and mode. A .authorstyleignore file can exclude paths using gitignore-style rules. --- title: "A technical article" date: 2025-04-02 source: devto language: en mode: technical published: true tags: - databases --- Keep the corpus representative and permitted for local processing. Remove private documents that do not belong in the experiment, and keep source provenance intact so you can identify why a profile changed. Generate and evaluate, with the boundary visible After analysis, the documented commands for generation and evaluation are: authorstyle write demo --prompt "Write about distributed databases" authorstyle evaluate demo Generation stores candidates, component scores, retrieved exemplars, and provider metadata for reproducibility. Evaluation uses document-level held-out splits, so chunks from one document are not placed in both profile and test sets. The project compares baselines such as generic, card, examples, hybrid, and full, and reports style distance, explicit stylometric fit, content adherence, naturalness heuristics, originality, and calibration percentiles. Do not interpret a high score as proof that a passage is authentically yours. The repository explicitly warns that it models recurring patterns from the supplied corpus, does not guarantee topic-independent style transfer, and does not automatically infer beliefs or personality. Privacy modes and security boundaries The default LOCAL_ONLY mode permits only local or mock providers. REMOTE_PROFILE_ONLY sends the task and Style Card but not raw corpus excerpts. REMOTE_EXEMPLARS also sends selected exemplar passages. These are materially different boundaries, so choose the mode deliberately rather than treating a remote provider as an implementation detail. The security policy also calls out prompt injection risks in Style Cards and generation prompts, unsafe file handling, accidental corpus disclosure, and unexpected network access when LOCAL_ONLY is configured. Never commit .env files, API keys, private corpora, or generated profile data unless you have a specific reason and have reviewed the consequences. Reproducible verification Run the project's test suite from the tagged checkout: python -m pytest -q The v0.2.1 checkout passed 24 tests in the verification environment. It also passed the CLI help command and the fixture path from initialization through analysis. Re-run those checks after changing dependencies or using a different Python version. A passing test suite validates the repository's current test cases; it does not validate the quality of your personal corpus or guarantee useful generated prose. Common failure modes The profile reflects the topic instead of the voice This is a documented risk. Separate style and semantic embeddings help, but recurring subjects can still correlate with style signals. Add varied documents and inspect modes instead of treating one narrow corpus as a complete author model. A mode has too little evidence Mode profiles require matching front-matter metadata. The methodology says insufficient evidence triggers warnings and fallback toward the global profile. That fallback is safer than pretending a small sample is a reliable mode. A remote provider receives too much Review the configured privacy mode before running write. Start with LOCAL_ONLY when testing ingestion and analysis. Remote generation is optional and must be explicit. The output copies a recognizable phrase The project includes originality checks for long exact spans and word n-gram overlap. Inspect the overlap diagnostics and keep generated text under human review, especially when the corpus contains published or third-party material. FAQ Does AuthorStyle fine-tune an LLM? No. The README describes a local research CLI with profiles, exemplars, encoders, candidate generation, scoring, and evaluation. Fine-tuning is not the documented quick-start path. Can it infer my beliefs or persona? No. Persona extraction is deferred in the current MVP. A style profile should not be treated as a biography. Is it production-ready? The package metadata marks the project as alpha. Treat it as an experiment that produces inspectable evidence and keep backups of any corpus or profile you care about. Takeaway The useful lesson in AuthorStyle is methodological: define style as measurable observations, keep the source corpus under a clear privacy boundary, and evaluate against held-out documents. That makes the experiment easier to inspect than a prompt-only imitation workflow, while still leaving room for the project's alpha-stage limitations. If you try this with your own corpus, which verification signal would you trust first: sentence-level stylometry, document-level holdout evaluation, or originality diagnostics? > AI assistance disclosure: This tutorial was researched and drafted with AI assistance. Commands, project details, limitations, and verification results were checked against the public AuthorStyle repository, its tagged release, and a local test run before publication.

Run a Safe Local Review of Env Team Vault Before Sharing .env Files --- title: "Run a Safe Local Review of Env Team Vault Before Sharing .env Files" published: true description: "Build Env Team Vault locally, inspect its .env sync path, verify the CLI, and identify the authentication boundary before using it." tags: typescript, node, tutorial, envvars --- Team environment variables are easy to share badly. A .env file sent through chat is convenient, but it is difficult to audit, easy to lose track of, and often contains more access than a teammate needs. Env Team Vault is an open-source, self-hosted Node.js and TypeScript application that organizes teams, applications, variables, API tokens, and audit events around local development configuration. The useful question is not only how to install it. The useful question is whether the current code and package are ready for the boundary where you want to use them. This tutorial shows a safe evaluation path for the current main branch and package version 1.0.0. You will build the project, inspect the CLI flow, and verify the environment-file route. This is a reproducible review, not a production recommendation. TL;DR - Clone paladini/env-team-vault and install its locked dependencies. - Run the TypeScript build and inspect the CLI package before sending real values. - The project documents Docker Compose, a web UI, SQLite with Prisma, and env-team-vault sync. - The current root CLI imports axios, but axios is not declared in the root package.json, so the documented npx env-team-vault --help check currently fails after npm ci. - The API controller also has an unauthenticated compatibility branch. Treat the current code as a local-development experiment until that boundary is fixed and tested. Prerequisites You need Git, Node.js, npm, and a disposable working directory. The repository declares Node.js type definitions for Node 20, while its Dockerfile starts from Node 18 Alpine. Use a current supported Node release for the local build, and record the exact version in your review. Do not put real API keys, production database URLs, or customer data into a first run. Use fake values and a disposable SQLite database. 1. Clone the current source and install it The repository README documents Docker Compose and a manual npm setup. Use the owner repository URL, not the placeholder your-org URL in its copy-paste examples. git clone https://github.com/paladini/env-team-vault.git cd env-team-vault npm ci The lockfile pins the application package at version 1.0.0 and includes its Prisma, Express, Passport, SQLite session, and TypeScript dependency tree. npm ci tests the package as committed rather than silently resolving a new dependency graph. Before continuing, inspect the installation result: npm audit npm run build The build compiles src/main.ts and the application layers into dist. It does not prove that the web server is configured correctly, that the database has been initialized, or that the CLI can run. Keep those checks separate. 2. Understand the local architecture The application combines Express with server-rendered EJS views. Prisma stores teams, users, applications, variables, API tokens, and audit logs in SQLite. The schema makes variable keys unique per application. The main configuration values are: NODE_ENV=development PORT=3000 SESSION_SECRET=use-a-random-local-value DATABASE_URL=file:./prod.db The source defaults the HTTP port to 3000, enables the SQLite-backed session store, and uses a fallback session secret when SESSION_SECRET is absent. That fallback is convenient for a local experiment but is not an acceptable production setting. The documented Docker path exposes port 3000 and persists the Prisma database and sessions in named volumes: docker compose up -d Open http://localhost:3000, register a disposable account, create a team, and create an application. Do not add a real secret while evaluating the flow. 3. Verify the documented CLI before trusting it The README documents a sync command that writes the response into a local .env file: npx env-team-vault sync <APP_ID> --url http://localhost:3000 --token <API_TOKEN> The current root bin/cli.js imports axios, fs, yargs, and Node path utilities. The root package.json declares yargs and the other server dependencies, but it does not declare axios. A fresh npm ci followed by npx env-team-vault --help therefore reaches the CLI file and fails with Cannot find module 'axios'. That failure separates a documented interface from a verified interface. Do not work around it by installing an undeclared package and then report the repository as working. A fix should add the dependency, update the lockfile, and add a smoke test for the executable path. The CLI also writes the server response directly to .env in the current directory. That is convenient, but it can overwrite an existing file. Use a disposable directory until the command has a confirmed backup or safe-write policy. 4. Inspect the authentication boundary The API route documented for the CLI is: GET /api/vault/:appId When an Authorization: Bearer ... header is present, VaultController looks up the API token, checks revocation, verifies team membership, verifies that the application belongs to that team, and records a SYNC_ENV audit event. However, the same controller has an else branch for requests without an authorization header. It checks only that the application exists and then returns the environment content. The route is registered as a public Express route, without the authentication middleware used by other parts of the application. This is the most important boundary in the current review. The README calls the project secure and audited, but the implementation currently permits an unauthenticated request for a known application ID. Do not expose this route to an untrusted network or put production secrets behind it. A safe contribution would remove the compatibility branch, require a valid token, add an integration test for unauthorized requests, and then document the changed contract. This conclusion comes from the current controller and route source, not from treating the README's security language as a guarantee. Source behavior wins when documentation and implementation differ. 5. Verify the expected result without real secrets For a local evaluation, the expected result is a buildable application and a reviewable data flow: 1. The server starts on port 3000 after the database has been initialized. 2. A disposable account can create a team and an application. 3. A fake variable such as DEMO_VALUE=not-a-secret can be associated with that application. 4. A valid API token can be used to request the application's .env representation. 5. The request creates an audit record when the token path is used. The source formats the response as plain text, so a successful response should look like this: DEMO_VALUE=not-a-secret Check the HTTP status, response content type, and resulting file. Then inspect the audit log in the application. Never use a successful response as evidence that the deployment is safe by itself. The unauthenticated branch and the default session secret still need to be addressed. Why this review order works The order follows operational risk. npm ci and npm run build establish a baseline. The CLI check tests whether the documented command exists in the dependency graph. The controller review tests authorization before any real value crosses the boundary. This is also why a green TypeScript build is not enough. TypeScript checks the files included in compilation. It does not guarantee that a JavaScript CLI has every runtime dependency, that a database migration exists, or that an HTTP route enforces the intended authorization policy. Failure modes and honest limitations The CLI reports a missing module Confirm the package manifest and lockfile before installing anything manually. The current root CLI's undeclared axios import is a repository issue, not a user configuration error. Prisma has no migration to apply The current repository contains prisma/schema.prisma but no migration directory in the checked-in Prisma folder. Treat database initialization as a development setup step and review the resulting database before using the application. Do not point this first run at an existing production database. A token request returns 401 or 403 Check the Bearer prefix, token revocation state, user team membership, and application team ownership. The controller intentionally rejects invalid or revoked tokens on the authenticated path. You need production secret management This project is explicitly positioned for local development variables. It is not a replacement for a mature production secret manager. The current unauthenticated route, fallback session secret, local SQLite storage, and missing CLI dependency are enough reason to keep the evaluation local and disposable. FAQ Is Env Team Vault a production secrets manager? No. The README describes a self-hosted local-development tool, and the current route implementation has an unauthenticated compatibility path. Treat it as an experiment or contribution target until that behavior changes. Why use npm ci instead of npm install? npm ci uses the committed lockfile and exposes undeclared runtime dependencies more reliably. It makes the first verification closer to what a clean deployment or package consumer will see. Should I publish the .env file generated by the CLI? No. Keep it outside version control, use fake values while testing, and check your ignore rules before running a sync command in a repository. Where is the source of truth for behavior? Use the repository README for the documented workflow, then compare it with the package manifest, Prisma schema, CLI implementation, and vault controller for current behavior. Takeaway Env Team Vault has a clear local-development idea: keep team variables in one self-hosted application, expose a CLI, and record synchronization events. The responsible way to evaluate it is to verify each layer independently. The current build succeeds, but the documented CLI has an undeclared runtime dependency and the API has an unauthenticated response path. Those findings should shape how you use the project and what you fix next. This tutorial was prepared with AI assistance for research organization and editorial review. The repository behavior, commands, and limitations were checked against the current public source and a fresh local checkout. Would you use a tool like this for disposable development environments, and which authorization test would you add first?

Agent AI cuma sekuat harness-nya: context file, rules, hooks, guardrails. harness-score skor harness itu dalam detik: L0-L4, 108 poin, nol LLM call & nol jaringan. npx harness-score --min-level 3 → gate CI. Bukan buat: cek apakah test kamu benar. paladini/harness-score t.co

🔗 GitHub: paladini/harness-score --- ✉️ If you’re into AI, ML, agents, and building real systems, join my newsletter (it’s free): dankornas.substack.com

Install Active Admin Claude Theme 0.2.0 in Rails --- title: Install Active Admin Claude Theme 0.2.0 in Rails published: true description: Install the Active Admin Claude Theme in Rails, choose the right asset pipeline for AA3 or AA4, and customize its design tokens safely. tags: ruby,rails,tutorial,activeadmin --- If an Active Admin backend works but still looks like a default admin panel, a theme gem can improve the interface without forcing a full frontend rewrite. The difficult part is choosing the correct integration path. Active Admin 3 uses Sass and Sprockets, while Active Admin 4 uses Tailwind CSS v4 and a different asset layout. This tutorial installs activeadmin-claude-theme version 0.2.0 in a Rails application, explains the version-aware generator, and shows how to customize its tokens. The gem is a community project inspired by Claude aesthetics. It is not affiliated with or endorsed by Anthropic. TL;DR Add the gem to an existing Active Admin application, run rails generate activeadmin_claude_theme:install, rebuild CSS when using Active Admin 4, and verify the generated asset entry before restarting Rails. Active Admin 4 keeps dark mode and uses CSS variables. Active Admin 3 receives a Sass theme and light mode only. Prerequisites The release documentation lists these requirements: - Ruby 3.2 or newer - Rails 7.2 or newer - Active Admin 4.0.0.beta22 or newer for the Tailwind path - Active Admin 3.2 or newer for the Sass path - Node.js and the Active Admin npm toolchain for Active Admin 4 The project is distributed under the MIT license. The 0.2.0 release is available on GitHub and RubyGems. The gem declares runtime dependencies on Active Admin >= 3.2.0, < 5 and Rails >= 7.2. This guide assumes that Active Admin is already installed. It does not replace the official Active Admin installation guide. Install the theme in Active Admin 4 Active Admin 4 uses Tailwind CSS v4. The theme's release documentation uses 4.0.0.beta22 as its documented example, so keep the Active Admin and npm versions aligned with the application you are actually maintaining. Add the gem to your Gemfile: gem "activeadmin-claude-theme", "~> 0.2" Install the bundle and run the generator: bundle install rails generate activeadmin_claude_theme:install The generator detects Active Admin's major version. For Active Admin 4, it prepares the Tailwind entry and the theme assets. Rebuild the stylesheet and restart Rails: npm run build:css bin/rails server The important detail is the separation between source and served CSS. The documented layout is: app/assets/tailwind/active_admin.css app/assets/builds/active_admin.css The first file is the Tailwind source. The second is the generated stylesheet served by the application. If the source file is placed directly in the served Propshaft path, the build can produce confusing results or fail to expose the expected active_admin asset. Install the theme in Active Admin 3 Active Admin 3 follows the Sprockets and Sass path. Add the same gem, but make sure the application has the Sass dependencies documented by the project: gem "activeadmin", "~> 3.5" gem "sprockets-rails" gem "sassc-rails" gem "devise" gem "activeadmin-claude-theme", "~> 0.2" Install the bundle and run the same generator: bundle install rails generate activeadmin_claude_theme:install For Active Admin 3, the generator updates app/assets/stylesheets/active_admin.scss to use the theme entry: @import "activeadmin_claude_theme/aa3/base"; Restart Rails after the asset change. Do not copy the Active Admin 4 Tailwind setup into an Active Admin 3 application. The two integration paths intentionally use different asset pipelines. Customize the design tokens The theme exposes a small set of semantic tokens instead of requiring selectors to be rewritten throughout the application. On Active Admin 4, override CSS variables after the theme import: :root { --claude-primary: #d4845f; --claude-canvas: #fff8f0; } .dark { --claude-canvas: #121110; } On Active Admin 3, set Sass variables before importing the theme base: $claude-primary: #d4845f; $claude-canvas: #fff8f0; @import "activeadmin_claude_theme/aa3/base"; The release's design reference documents the palette, typography, spacing, and token naming. The default primary color is #cc785c, the canvas is #faf9f5, and the semantic token prefix is --claude- for CSS variables. Prefer semantic tokens for global changes. If a single screen needs a special treatment, use a narrow application-level selector rather than changing the theme's generated files. This keeps upgrades reviewable and makes it clear which choices belong to the application. Verify the generated integration After the generator finishes, verify the files before debugging the browser. For an Active Admin 4 application, check that the Tailwind source and build output exist: Test-Path app/assets/tailwind/active_admin.css Test-Path app/assets/builds/active_admin.css On a Unix-like shell, the equivalent check is: test -f app/assets/tailwind/active_admin.css test -f app/assets/builds/active_admin.css Then rebuild and inspect the generated CSS for one token that you changed: npm run build:css grep -n "claude-primary" app/assets/builds/active_admin.css On Windows PowerShell, use this instead of grep: Select-String -Path app/assets/builds/active_admin.css -Pattern "claude-primary" For Active Admin 3, verify the Sass import and run the normal Rails asset precompile or development server path used by the host application: grep -n "activeadmin_claude_theme/aa3/base" app/assets/stylesheets/active_admin.scss bin/rails assets:precompile The expected result is an Active Admin page using the theme's warm palette. On Active Admin 4, the built-in dark mode and mobile drawer remain Active Admin features. The theme's AA4 override map explains which partials the gem overrides and which hooks it deliberately preserves. Common failure modes The page is unstyled after installation For Active Admin 4, run npm run build:css or the application's documented bin/rails css:build command, then restart Rails. Also confirm that the source is under app/assets/tailwind and the generated file is under app/assets/builds. The generator changes the wrong file The generator detects the installed Active Admin major version. Check the bundle before running it. An application with a stale or conflicting Active Admin dependency can be classified differently from what you expect. Active Admin 3 reports a Sass error Confirm that sassc-rails or a compatible Sass pipeline is installed and that the file imports activeadmin_claude_theme/aa3/base after your own variable overrides. You expect dark mode on Active Admin 3 That is not supported by this release. The project documents dark mode for Active Admin 4 only because Active Admin 3 does not provide the same native dark-mode mechanism. You treat the theme as an official Claude product Do not. The README and FAQ explicitly describe it as a community theme. The name and visual inspiration do not provide any Anthropic affiliation, endorsement, security guarantee, or product compatibility promise. FAQ Can one Gemfile support both Active Admin 3 and 4? The gem supports both major versions, but an individual application should use one Active Admin integration path at a time. The project's own development setup uses separate dummy applications and dependency files for its version coverage. Does the theme replace all Active Admin templates? No. The AA4 documentation describes minimal partial overrides and preserved Active Admin hooks. It remaps Tailwind colors, adds semantic tokens, and customizes selected header and navigation partials. Can I use it with Propshaft? The FAQ documents Propshaft support for Active Admin 4 when the standard Tailwind and cssbundling setup is followed. Active Admin 3 typically remains on Sprockets. What should I customize first? Start with --claude-primary and --claude-canvas on Active Admin 4, or their Sass equivalents on Active Admin 3. These two choices demonstrate the token flow without coupling your application to internal selectors. Takeaway The useful part of activeadmin-claude-theme is not only its palette. Its version-aware generator makes the Active Admin 3 and 4 boundary explicit, while its token model gives Rails teams a small, reviewable customization surface. Install against the release that matches your application, verify the generated asset path, and treat Active Admin 3 and 4 as separate pipelines. Have you kept one Active Admin application compatible with both major asset pipelines, or did you choose a clean upgrade to Active Admin 4? Share the constraint that shaped the decision. > AI assistance disclosure: AI assistance was used to organize this tutorial and draft prose. Project behavior, versions, commands, limitations, and links were checked against the public repository, the v0.2.0 release, the gem metadata, and the project documentation.

Add an Evidence-Backed Repository Listing to Harness Maturity Showcase --- title: "Add an Evidence-Backed Repository Listing to Harness Maturity Showcase" published: true description: "Learn how to scan a public repository, pin its evidence, and submit a reproducible Harness Maturity Showcase entry." tags: opensource, github, tutorial, githubpages --- If you publish a maturity score for an open-source repository, readers need more than a number. They need to know which commit was measured, which scanner produced the result, and where the raw evidence can be inspected. Harness Maturity Showcase is a small static site that makes those checks visible. It stores repository listings as data, links each listing to public evidence, and validates the rules in CI. This tutorial shows how to add one reproducible full report without changing the site's ranking code. TL;DR You will scan a public repository with the published harness-score package, commit the generated JSON report to that repository, add one record to data/projects.json, and run the showcase's deterministic checks. The important part is the evidence chain: repository, measured commit, scanner version, score, and public report must agree. Prerequisites You need: - Git and a GitHub account. - Node.js 20 or newer. The showcase declares node >=20. - A public GitHub repository that you are allowed to scan and modify. - Permission to open a pull request in your fork of the showcase. The showcase is MIT-licensed. It is a static HTML, CSS, and JavaScript site with no runtime dependencies. Its own checks run with Node's built-in test runner. Understand the two contribution paths The project supports two kinds of entry. A full report participates in the numeric ranking. It includes score, maxScore, level, toolVersion, a measured commit SHA, and a link to a committed JSON report. A badge-only entry is different. It records a public maturity claim from a repository README, but it does not claim a numeric score. The validator rejects badge entries that include score or maxScore. Use the full-report path when you can publish the scanner output and identify the exact commit. Use badge-only when the repository displays an official badge but does not publish a full report. Do not turn a badge claim into a measured result by inference. 1. Start from a clean checkout Create a working copy of the repository you want to measure. The scanner reads files, so the result should be tied to a commit that another person can retrieve later. git clone https://github.com/your-name/your-project.git cd your-project git checkout --detach YOUR_COMMIT_SHA git rev-parse HEAD Record the 40-character SHA printed by the final command. The showcase compares reports within the same scanner version and stores the measured commit for reproducibility. The current showcase refresh documents the same rule: reports are pinned to public default-branch commits, and future refreshes use a new dated directory instead of rewriting historical evidence. 2. Generate the report with the published scanner Run the published package from outside the repository checkout. The documented command writes JSON to standard output and leaves the scanned project unchanged. mkdir -p reports npx --yes harness-score@1.8.1 /path/to/pinned-checkout --json > reports/harness-score.json On Windows PowerShell, the equivalent redirection is: New-Item -ItemType Directory -Force reports | Out-Null npx --yes harness-score@1.8.1 C:\path\to\pinned-checkout --json | Out-File -Encoding utf8 reports\harness-score.json Use the version that you actually ran in the showcase record. Do not copy a score from a different scanner version. The current release reports version 1.8.1, and the package requires Node.js 18 or newer; the showcase itself requires Node.js 20 or newer. Inspect the report before committing it. Confirm that its tool.version, level, score, maximum score, and measured commit describe the checkout you intended to scan. 3. Publish the evidence in the scanned repository Commit the report to the repository you measured. A simple layout is enough: . └── harness-score.json git add harness-score.json git commit -m "Add Harness Score evidence" git push origin YOUR_BRANCH The report URL in the showcase must be public and stable, for example: https://github.com/your-name/your-project/blob/main/harness-score.json If you measure a historical commit, link to the report at that commit or to a branch that preserves the exact JSON. A link that later changes to a different report weakens the evidence chain. 4. Add one full-report record Fork the showcase, edit data/projects.json, and add one object. The contribution guide requires source: "study" for a full report. { "repo": "your-name/your-project", "category": "community", "level": 3, "score": 82, "maxScore": 105, "toolVersion": "1.8.1", "commit": "0123456789abcdef0123456789abcdef01234567", "source": "study", "evidence": "https://github.com/your-name/your-project/blob/main/harness-score.json" } Replace every illustrative value with the corresponding value from your report. The repository name must use owner/name syntax, and each repository may appear only once. The commit must be a complete 40-character hexadecimal SHA. The category field is part of the site's data model, while the validator focuses on the repository name, source, numeric fields, commit, scanner version, and evidence URL. Keep the record small and avoid adding claims that the report does not contain. 5. Validate before opening the pull request From the showcase checkout, install its lockfile and run the documented check: npm ci npm run check The check script runs npm run validate and npm test. Validation checks repository names, duplicates, levels from 0 through 4, numeric bounds, scanner versions, complete commit SHAs, public GitHub evidence links, and the badge-only rules. The test suite checks the page structure, report reproducibility links, scanner-version boundaries, historical rankings, and the separation between full reports and badge-only entries. A passing check confirms the repository's data and site invariants. It does not replace human review of the evidence URL. Open a focused pull request that changes one listing. Maintainers verify that the linked evidence is public and that the values in data/projects.json match it. If the measured repository changes substantially, generate a new report rather than silently editing the old one. Why the evidence model matters A score without a commit is hard to reproduce. A score without a scanner version is hard to compare. A score without a public report asks reviewers to trust a summary they cannot inspect. The showcase keeps those concerns separate. Rankings are scoped to a scanner version, full reports point to immutable evidence, and badge-only records stay outside numeric ranking. This makes a lower score interpretable: it may reflect the repository, the scanner version, or the measured commit, and the data tells you which inputs to investigate. The same design also limits what the site can claim. A passing GitHub Actions job proves that the data satisfies structural checks. It does not prove that a repository is secure, production-ready, or better than another project in every engineering dimension. Failure modes and honest limits The report is rejected because the commit is invalid Check that commit contains exactly 40 hexadecimal characters. Do not use a short SHA, a branch name, or the commit that happened after the scan. A full report does not appear in the ranking Confirm that source is study, that toolVersion is a semantic version, and that score and maxScore are numbers within bounds. Badge-only entries intentionally do not receive numeric ranking. The score changed after a refresh Compare the scanner version, measured commit, and repository contents. The project documents that changes between scanner versions or repository revisions are not, by themselves, evidence of improvement or regression. The site check passes but the evidence is wrong This is a review failure, not a validator failure. Open the evidence URL, compare the JSON fields with the record, and verify that the URL is public before asking for review. Security boundary The scanner is a read-only file inspection tool for this workflow, but running any package still deserves normal supply-chain care. Pin the version in reproducible instructions, review the package source and lockfile policy appropriate to your environment, and do not scan private repositories or publish sensitive report contents without authorization. FAQ Can I submit a private repository? No. The evidence URL must be public, and the showcase is designed for inspectable open-source data. Can I submit a score from an older Harness Score version? Yes, when the report and metadata satisfy the schema, but rankings are separated by scanner version. Use the current published version for a new contribution unless you have a reason to preserve historical evidence. Does a passing score make a repository mature? It measures the checks implemented by Harness Score. It does not certify software quality, security, or operational readiness. Can I add several repositories in one pull request? The contribution guide asks contributors to keep a submission focused on one repository. Follow that review boundary unless maintainers ask for a batch change. Takeaway The useful unit is not a maturity number. It is a number connected to a scanner version, a measured commit, a public report, and a validation path that another contributor can repeat. If you maintain an open-source repository with an official Harness Score result, submit the smallest complete evidence record you can defend. What additional evidence would make a maturity listing more useful to you: historical snapshots, CI status, or a clearer explanation of each check? > AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, project behavior, version claims, and validation results were checked against the cited repository, its current documentation, and the published package metadata.