paladini

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.

Use mcp-me v0.6.0 to Share One Local AI Profile Across MCP Clients --- title: "Use mcp-me v0.6.0 to Share One Local AI Profile Across MCP Clients" published: true description: "Configure one local YAML profile for Cursor, VS Code, Windsurf, and Claude Desktop with mcp-me v0.6.0, then validate it before serving." tags: ai, mcp, tutorial, cli --- TL;DR If you use more than one MCP-compatible AI client, repeating your background in every tool is tedious and easy to get wrong. mcp-me v0.6.0 gives you one local profile directory, a YAML configuration file, and an MCP server that clients can read. This tutorial creates the profile, validates it, configures the same server for Cursor, VS Code, and Windsurf, and explains where Claude Desktop fits. The setup uses the published mcp-me@0.6.0 package, not an unreleased checkout. Prerequisites You need: - Node.js 20 or later. The package declares node >=20.0.0 in its release metadata. - npm and a terminal. - One MCP-compatible client such as Cursor, VS Code with GitHub Copilot, Windsurf, or Claude Desktop. The project is open source under the MIT license. The v0.6.0 release is the stable reference for this walkthrough, and the package manifest records the version and Node.js requirement. Create and validate one profile You can run the CLI without a global installation through npx. This keeps the example tied to the exact version used in the tutorial. npx --yes mcp-me@0.6.0 init npx --yes mcp-me@0.6.0 validate With no directory argument, v0.6.0 uses ~/.mcp-me as the default profile location. The init command creates the YAML templates, .mcp-me.yaml, and agent instruction files. The validate command checks the profile YAML files against the project's schemas. The command output should end with a successful validation message for the profile files. In a clean smoke test, the release created 11 files and validated identity, career, skills, interests, personality, goals, projects, and FAQ data. Now inspect the generated configuration: cat ~/.mcp-me/.mcp-me.yaml On Windows PowerShell, use this equivalent command: Get-Content "$HOME\.mcp-me\.mcp-me.yaml" The file separates data generators from live plugins. Start with a small configuration and replace the example values with your own public handles: generators: github: your-username devto: your-username plugins: github: enabled: true username: your-username The configuration is not your profile data. It tells mcp-me which sources to use when it generates profile files and which live plugins should be available to the server. Keep the generated YAML files reviewable, and validate after editing. Generate profile data locally After editing .mcp-me.yaml, run the generator: npx --yes mcp-me@0.6.0 generate npx --yes mcp-me@0.6.0 validate The v0.6.0 README documents username-based generators and the default profile path. Many public sources do not need API keys, but that is source-dependent. A provider can still require authentication, rate limits, or a local export. Treat each generated file as data to review before making it available to an assistant. If you want an isolated profile for a project or experiment, pass a directory explicitly instead of changing the default: npx --yes mcp-me@0.6.0 init ./my-ai-profile npx --yes mcp-me@0.6.0 validate ./my-ai-profile npx --yes mcp-me@0.6.0 generate ./my-ai-profile This explicit path is useful for testing because it makes the data boundary obvious. It also lets you keep separate profiles for work and personal use. Connect the same server to multiple clients The important idea is that every client points to the same command and profile directory. The server reads the profile when it starts, so the clients do not need separate copies of your YAML files. The simplest cross-client command is: npx -y mcp-me serve For Windsurf, add an entry to ~/.codeium/windsurf/mcp_config.json: { "mcpServers": { "me": { "command": "npx", "args": ["-y", "mcp-me", "serve"] } } } For Cursor, place the same server entry in .cursor/mcp.json in a project, or in the client configuration used for global servers: { "mcpServers": { "me": { "command": "npx", "args": ["-y", "mcp-me", "serve"] } } } VS Code uses a different top-level key. In .vscode/mcp.json, use servers: { "servers": { "me": { "command": "npx", "args": ["-y", "mcp-me", "serve"] } } } These client examples are taken from the v0.6.0 README configuration section. Claude Desktop can use the .mcpb asset attached to the v0.6.0 GitHub release, or the manual MCP configuration documented by the project. Verify the server boundary Before connecting a client, ask the CLI for help and validate the profile again: npx --yes mcp-me@0.6.0 --help npx --yes mcp-me@0.6.0 validate Then start the server in a terminal: npx --yes mcp-me@0.6.0 serve An MCP client normally launches this process itself over standard input and output. The useful verification is therefore client-side: connect the me server, ask the client to read a profile resource, and confirm that the answer matches the YAML you reviewed. Do not treat a successful process launch as proof that every generator or plugin works. If you need to make the profile location explicit, set MCP_ME_PROFILE_DIR in the client process environment or pass a directory to the serve command. The release README documents both options. Why this works The profile files and the .mcp-me.yaml configuration form a local source of context. The MCP server exposes that context through the protocol, while each client remains responsible for deciding when to read it. This is different from copying a long instruction block into every client: the data has one canonical location, and changes can be reviewed with normal file tools. The design also leaves a useful boundary between generated data and live integrations. Generated YAML can be inspected before use. Plugins can provide current values when an assistant queries them. That separation makes it easier to disable a plugin, remove a field, or keep a sensitive category out of a profile. Failure modes and limitations The client cannot find npx GUI applications may not inherit the same PATH as your terminal. Check the client documentation for environment configuration, or use the absolute path to your Node.js installation. The error is a process discovery problem, not a profile validation failure. Validation fails after editing YAML Run validate with the profile directory and read the first reported file. Fix the schema or value, then run validation again. Do not connect an unvalidated profile and assume the client will explain the problem. A source returns incomplete data Generators depend on the source's public API, feed, or export format. A valid local profile does not prove that a remote source returned complete data. Review the generated file and consult the source-specific documentation before relying on it. Local does not mean risk-free The project is designed around local YAML files, but any MCP client that can read those files may place their contents into model context. Do not put passwords, private keys, access tokens, or secrets in the profile. Use the project's documented plugin settings and your operating system's file permissions. The MIT license and local execution do not constitute a security guarantee. The tutorial also uses the stable v0.6.0 release. The repository's default branch may contain newer or unreleased behavior, so check the current changelog before copying commands into a new environment. FAQ Do I need to install mcp-me globally? No. npx --yes mcp-me@0.6.0 is enough for the commands above. A global npm installation is convenient for repeated use, but pinning the version makes a tutorial and a reproducible check clearer. Can different clients use different profiles? Yes. Pass an explicit directory or set MCP_ME_PROFILE_DIR for a client process. Use separate profiles when the audiences or sensitivity of the data differ. Does mcp-me remember previous conversations? No. It exposes profile data and configured live resources through MCP. Conversation history, model behavior, and client-side context policies remain separate concerns. Takeaway Use one reviewed profile directory as the shared context layer, validate it after every edit, and point each MCP client at the same mcp-me serve command. Start with public, low-risk fields. Add generators and plugins only when you understand what data they read and what the client can send to a model. What is the first profile category you would keep local and shared across your AI tools: skills, projects, career history, or something else? > AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, version claims, configuration examples, and smoke-test result were checked against the mcp-me v0.6.0 release and its primary project documentation.