DEV Community

HTML lang and SEO: Check the Language Your Page Declares

Uriel Bitton — Sun, 01 Nov 2026 14:46:59 +0000

Set the HTML lang attribute to describe the page’s actual predominant language. Then verify that the delivered page and its language label agree. This helps users and assistive technology; it should not be presented as a command that makes Google detect a language or target a country.

Google explicitly says it uses algorithms, rather than HTML lang or hreflang, to detect a page’s language. That makes the technical diagnosis more precise: a wrong language label is worth fixing, but an unwanted search-language result needs its own investigation. Do not promise that changing the attribute will resolve both.

Keep three observations separate

Take a fictional documentation page intended for French-speaking readers. Its route contains a French-looking path, most of its explanatory text is French, but a shared layout still declares English on the root HTML element. These are three different observations: route naming, visible language, and programmatic language.

The mismatch is not repaired by pointing at the URL and saying the language is obvious. A person can infer meaning from the page while a user agent receives a different label. Equally, a French label on an untranslated English page would not make that page French.

Before changing anything, record the exact public URL and what the page currently delivers. Keep regional audience requirements separate from language correctness. A page can be written in French for readers in several countries, or use the same language across regional variants with different commercial conditions.

Visible content: what language dominates the actual answer?
Declared language: what does the root HTML element identify?
Audience and variants: who is the page for, and which related versions exist?

Understand what the language label helps readers do

W3C’s Language of Page explanation describes identifying the default human language so user agents and assistive technologies can present content appropriately. Screen readers can use the correct pronunciation rules. This is a user-facing reason to provide an accurate label, independent of a ranking claim.

Apply that purpose to the fictional page. If its main answer is French, a default English label is a defect to investigate in the template or localization pipeline. Correcting it helps the programmatic description match what the reader receives.

A non-empty value alone is not a complete quality check. The label also needs to represent the content. A quick automated check can flag a missing attribute while missing a plausible but incorrect value inherited from another route. Include an editorial review of the visible language when verifying a translated page.

Inspect the document that actually reaches the browser

Open the public route directly, rather than reaching it only through an already localized session. In browser developer tools, inspect the root HTML element and read its lang value. Compare it with the main text, headings, navigation, and any important notices. Save the route and the observation date.

Then follow a normal internal navigation path to the same page. If the site changes content without loading a whole document, check the language label again after navigation. A correct initial document does not establish that the attribute stays correct during every route transition.

In the hypothetical docs site, direct loading might deliver the expected French label while a client-side transition leaves the previous page’s English value behind. That is a proposed failure case to test, not an observed result from a real site. If it occurs, the repair belongs in the route or layout behavior that owns the value.

Also review the state a new visitor receives. Do not let yesterday’s language selection stand in for the default experience. Record any visible preference or account condition that changes what is served. This turns the check into a reproducible observation rather than an unexplained screenshot of one session.

Handle mixed-language content deliberately

A translated article may retain a product name, a quoted phrase, or an original-language example. Those fragments do not necessarily change the predominant language of the document. Start with the main answer and consider what a reader is actually being asked to understand.

W3C’s guidance explains choosing the language used most when a page contains several languages, with the first used as the default when languages are used equally. Its related guidance addresses language changes within parts of a page. Keep document-level and passage-level labeling as separate review tasks.

For a practical handoff, identify the mixed-language passage and ask whether its treatment is intentional. A long untranslated warning is a different problem from a short product name. If a critical limitation remains in another language, adding a label does not substitute for translating the information the intended audience needs.

Use Google’s language guidance within its scope

Google’s localized-pages documentation says hreflang describes relationships among localized variations. It separately states that Google does not use hreflang or the HTML lang attribute to detect the language of a page. Avoid collapsing these jobs into a single “language tag” repair.

In the fictional site, fixing the English root label on the French page addresses a real mismatch. If search still shows an English version for a particular query, that is a separate observation. Inspect the actual result, relevant page content, and variant setup instead of repeatedly changing the root label.

The same caution applies to AI visibility. A correct lang value is not a documented universal requirement for being cited by ChatGPT, Claude, or Gemini. Do not generalize Google’s language-detection statement into a claim about every system either. State the engine, the behavior documented, and the limit of the evidence.

Review representative routes, not one successful screenshot

Build a small review set from the templates that can produce different language states. Include a directly loaded translated article, a page reached from another language, a fallback page, and an important error or access notice. Use the routes your product actually exposes.

For each case, record intended language, observed main-content language, declared root language, and relevant navigation state. Add whether the result was checked before and after client navigation. Keep expected and observed values in separate fields so the chosen implementation cannot quietly redefine the requirement.

Ask the responsible developer or localization owner to explain which component owns the value. A shared shell, server template, and route-level change can otherwise overwrite each other. The acceptance check should include the affected transitions, not just the single page used to discover the defect.

A representative sample still has limits. It does not prove that every route and language combination works. Record untested templates and prioritize ones that carry important buyer answers. The goal is a clear, bounded check that another person can repeat.

Verify the repair against the problem it was meant to solve

After the normal authorized release, reopen the public routes and repeat the recorded transitions. Confirm that the label agrees with the intended main-content language and that the content itself has not fallen back to an unexpected version. Keep evidence of the actual delivered state.

If the change also affects pronunciation or other assistive behavior, use an appropriate accessibility review rather than inferring the whole experience from one attribute. A corrected label is one part of a usable multilingual page.

Track search presentation and AI answers separately if those are part of the project. Save the question or query, surface, date, mode, and linked destination; repeat observations before claiming a stable change. The defensible immediate result is that a defined set of pages now declares the language it actually presents. That is useful technical work even when no discovery gain has yet been demonstrated.

Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.

Subscribe for practical ways to grow your brand's visibility in search and AI answers.

Explore HoneyWeRank for SEO and AI visibility.

Sources

Choosing the right API gateway can make a huge difference in routing, security, and performance. A useful comparison for developers looking to simplify API management and avoid common routing headaches.

Michael Johnson — Sun, 01 Nov 2026 14:46:32 +0000

Dev Stack Hub

Oct 31

6 Best API Gateways for Developers Breaking Their Routing Logic

#discuss #api #devops #backend

19 min read

ASP.NET Core 'Error Unprotecting the Session Cookie': Why Your Keys Disappear on Deploy

Kausar Raza — Sun, 01 Nov 2026 14:45:25 +0000

You deploy an ASP.NET Core app, or IIS recycles its app pool overnight, and the log fills up with this:

warn: Microsoft.AspNetCore.Session.SessionMiddleware[7]
      Error unprotecting the session cookie.
      System.Security.Cryptography.CryptographicException: The key {83f2e736-3392-4263-9f0f-ad943c51fe3e} was not found in the key ring.

At the same time, users report being logged out, and forms fail with "The antiforgery token could not be decrypted". The session warning is just the visible part. The cause is that the app has lost the keys it used to encrypt its cookies. Every cookie issued before that moment is now unreadable.

This happened on the API behind this site. It runs on IIS under Plesk, where the app pool has no loaded user profile, so ASP.NET Core kept its keys in memory and threw them away on every restart. Below is what I reproduced, the exact messages each cause produces, and the fix. The deploy side of IIS and Plesk 500 errors is in the Plesk 500 errors post.

The short fix: store the Data Protection keys in a folder that survives restarts and deploys, and give the app a fixed name: services.AddDataProtection().PersistKeysToFileSystem(new DirectoryInfo(@"App_Data\keys")).SetApplicationName("MyApp"). Then make sure your deploy never deletes that folder. Users who already have old cookies will be logged out once more, and after that it stops.

What the error actually means

ASP.NET Core doesn't store session data, login tickets or antiforgery tokens in plain text. It encrypts them with the Data Protection system, which keeps a set of keys called the key ring. Each encrypted payload carries the ID of the key that made it. When a request comes in, the app looks up that ID in its ring. If it isn't there, you get "The key {...} was not found in the key ring".

Three components report it, in three different ways:

Session middleware logs "Error unprotecting the session cookie" as a warning, then quietly starts a new, empty session.
Cookie authentication logs "Cookies was not authenticated. Failure message: Unprotect ticket failed", but only at Information level. With the default "Microsoft.AspNetCore": "Warning" setting in appsettings.json, you never see it. The user is just signed out.
Antiforgery throws AntiforgeryValidationException: "The antiforgery token could not be decrypted", which usually surfaces as a 400 on form posts.

That's why the session warning is the one people search for. It's the only one that shows up in a default log, even though the logouts hurt more.

What I tested

I built a minimal ASP.NET Core 9 app (runtime 9.0.8, Windows 11, Kestrel) with cookie sign-in, session and antiforgery. I signed in with curl, kept the cookie jar, restarted the app with a different key setup each time, and sent the old cookies back. These are the results.

1. Keys persisted, plain restart: nothing breaks

With keys stored in a folder and the app restarted on the same folder, the user was still signed in and the old antiforgery token still validated. This is the control. One thing did reset: the session value was empty after the restart. That isn't a key problem. AddDistributedMemoryCache() keeps session data in process memory, so a restart loses it even when the cookie decrypts fine. If you need sessions to survive restarts, use SQL Server or Redis for the session store as well.

2. Key folder wiped: "was not found in the key ring"

Pointing the restarted app at an empty folder is exactly what a deploy does when it deletes the old site folder, including App_Data. The user came back anonymous, the antiforgery post failed with "The antiforgery token could not be decrypted", and the log showed the error from the top of this article, naming the old key's ID. The app also silently created a new key, logging:

No XML encryptor configured. Key {53f0f160-...} may be persisted to storage in unencrypted form.

3. Same keys, different application name: "The payload was invalid"

Data Protection isolates apps from one another using an application name. If you don't set one, it is derived from the app's content root path. So moving the site to a different folder, or swapping deployment slots, can change it. I kept the same key folder and changed only SetApplicationName from SiteA to SiteB. The keys were found, but nothing decrypted:

warn: Microsoft.AspNetCore.Session.SessionMiddleware[7]
      Error unprotecting the session cookie.
      System.Security.Cryptography.CryptographicException: The payload was invalid.
info: Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationHandler[7]
      Cookies was not authenticated. Failure message: Unprotect ticket failed

The antiforgery error changed too, to "The required antiforgery cookie ".AspNetCore.Antiforgery.6asUPwDiMTw" is not present". The suffix of that cookie name is derived from the application name, so the app was looking for a cookie with a different name. If you see "payload was invalid" rather than "key not found", look at the application name before the keys.

4. Where the keys go by default

With no configuration, a normal Windows user account gets this at startup:

User profile is available. Using 'C:\Users\<you>\AppData\Local\ASP.NET\DataProtection-Keys' as key repository and Windows DPAPI to encrypt keys at rest.

That's why it works on your machine. An IIS app pool doesn't have that folder unless "Load User Profile" is on, and on shared hosting such as Plesk you often can't control that setting. When there is no profile and no registry hive set up for the pool, the framework uses an in-memory ring. I couldn't reproduce that fallback outside IIS, but its warning is in the framework itself (Microsoft.AspNetCore.DataProtection.dll, 9.0.8):

Neither user profile nor HKLM registry available. Using an ephemeral key repository. Protected data will be unavailable when application exits.

If that line is in your startup log, every app pool recycle, idle timeout and deploy logs your users out.

The fix

Three settings, all in Program.cs before builder.Build(). This is the configuration this site's API uses now:

var keysDir = new DirectoryInfo(Path.GetFullPath("App_Data/keys", builder.Environment.ContentRootPath));
keysDir.Create();

var dataProtection = builder.Services
    .AddDataProtection()
    .PersistKeysToFileSystem(keysDir)          // keys survive restarts and recycles
    .SetApplicationName("MyApp");              // fixed, so moving the folder or slot doesn't change it

if (OperatingSystem.IsWindows())
{
    dataProtection.ProtectKeysWithDpapi(protectToLocalMachine: true);  // encrypt key files at rest
}

Notes on each line:

The folder must be outside the release files. If your deploy copies the site over App_Data, or deletes and re-extracts it, the keys go with it. Keep App_Data out of the delete step, the same way you keep uploads.
Use ProtectKeysWithDpapi(protectToLocalMachine: true), not the per-user default. An app pool has no user profile to hold a per-user DPAPI key. Machine scope works without one. The trade-off is that the key files can only be decrypted on the same machine.
Set the application name once and never change it. Changing it logs every user out, the same as losing the keys.

After the change, the first deploy logs everyone out once. That's expected: the old cookies were encrypted with keys that no longer exist, and there's nothing to recover them with. From then on, restarts and recycles keep the same keys.

How to check it worked

Sign in, then recycle the app pool or restart the app.
Check that you are still signed in. If you are, the keys survived.
Check the log. The "User profile is available" line should be gone, and no "Neither user profile nor HKLM registry available" line should appear. Either one would mean the keys went to memory.
Check that App_Data\keys contains key-*.xml files, and that the timestamps don't change on every restart.

FAQ

What does 'The key was not found in the key ring' mean in ASP.NET Core?

ASP.NET Core encrypted a cookie or token with a key that the app no longer has. The key ring is empty or missing that key, so the payload can't be decrypted. The usual cause is keys stored in memory, or a key folder that was wiped during a deploy.

Why am I logged out every time I deploy or recycle the app pool?

The Data Protection keys are kept in memory, or in a folder that the deploy deletes. The new process has different keys, so cookies from before can't be decrypted. Persist the keys to a folder outside the release files, with PersistKeysToFileSystem.

What does 'The payload was invalid' mean in ASP.NET Core Data Protection?

The app found the key but the cookie still couldn't be decrypted. A common cause is a different application name. Check SetApplicationName, and check that the app isn't running from a different folder or deployment slot with a different default name.

What is the difference between 'key not found' and 'payload was invalid'?

'Key not found' means the key ring doesn't contain the key that encrypted the cookie, so the keys were lost or moved. 'Payload was invalid' means the key was found, but the app name or key data doesn't match. Keys first, then application name.

Where should ASP.NET Core store Data Protection keys on IIS?

In a folder that the app pool identity can write to, outside the release folder, for example App_Data/keys. Protect the key files with ProtectKeysWithDpapi(protectToLocalMachine: true), since an app pool usually has no user profile for per-user DPAPI.

What does 'No XML encryptor configured' mean?

The Data Protection keys are being saved to disk without encryption. It's a warning, not an error. Fix it with ProtectKeysWithDpapi on Windows, or with a certificate or Key Vault on other hosts.

Does the session warning 'Error unprotecting the session cookie' mean my users are logged out?

Not directly. It's the session middleware, which starts an empty session. Login is handled by cookie authentication, which logs a separate message at Information level. Check that too, because the warning alone doesn't show it.

Originally published on knowledgemarkg.com.

Verifying CVE-2026-110264 Remediation Beyond the Upgrade Button

facilishz — Sun, 01 Nov 2026 14:45:08 +0000

Verifying CVE-2026-110264 Remediation Beyond the Upgrade Button

An upgrade is a change, not yet a clean remediation result. For CVE-2026-110264, the verification question has two parts. Is every self-managed GitLab workload running a fixed release? Did the vulnerable period create evidence that the server was accessed or altered? The first answer comes from deployment records. The second requires log, identity, and downstream-system review.

GitLab disclosed CVE-2026-110264 on October 21, 2026. The vulnerability is an integer overflow in regular expression compilation that, under certain conditions, could allow unauthenticated code execution on a GitLab server. GitLab rates it CVSS 10.0 and lists affected CE/EE versions from 7.0 before 18.11.13, 19.0 before 19.0.10, 19.1 before 19.1.9, 19.2 before 19.2.9, 19.3 before 19.3.6, 19.4 before 19.4.3, and 19.5 before 19.5.1.

Confirm the software identity

Use the fixed releases 18.11.13, 19.0.10, 19.1.9, 19.2.9, 19.3.6, 19.4.3, or 19.5.1 according to the supported branch. Confirm the reported version on every node and compare it with the package or container digest recorded by the deployment system. A load balancer may route to a node that was missed during a rolling update.

Check GitLab.com and Dedicated assumptions separately from self-managed infrastructure. GitLab.com was patched. Dedicated tenants running 19.3.5-internal0 and 19.4.2-internal0 or later include these fixes. A third-party managed service needs the provider's confirmation for the specific tenant and version.

Test the service, not just the banner

Open a repository, render a merge request, run a small pipeline job, and perform a permitted administrative check. Confirm background workers are processing jobs and that no migration errors are recurring. In a clustered environment, verify health and version consistency across nodes.

Check that the two GitLab detections, "Onigmo native worker crash" and "Org mode render error burst," continue to deliver events after the upgrade. This catches broken log collection and helps identify a workload that rolled back or was left on an older image.

Review the exposure window

The public advisory does not disclose the exact triggering request, so a search for one known exploit string is insufficient. Use the GitLab detections as starting points. Correlate crash and error events with web requests, worker restarts, process creation, outbound network connections, and changes to repositories or pipelines.

Review audit events for new deploy keys, tokens, webhooks, runner registrations, and access changes. Inspect source and CI/CD history for modifications that could cause a later trusted build or deployment to execute attacker-controlled code. Compare package publications and release artifacts with the expected release process.

Handle credentials and sessions

If exploitation is credible, rotate secrets available to the GitLab application and connected services. Revoke active sessions and tokens that cannot be rotated. Coordinate with cloud, package registry, monitoring, and deployment owners so the rotation is complete rather than limited to one application setting.

Keep evidence of the old and new credential state without storing the secret values in the case record. Document who completed each rotation and which dependent system accepted the new credential. Repeat the functional checks after rotation.

Treat network controls correctly

Restricting public access and outbound traffic can reduce exposure and limit attacker movement. These controls do not remove the vulnerable code. A WAF rule has no verified efficacy without a known request pattern, and authentication in front of the application may not cover the unauthenticated vulnerable path.

CERT-EU recommends updating affected assets quickly, prioritizing internet-facing systems, and assessing for compromise. That assessment should remain open when a crash or render-error event cannot be explained, even if the software is now patched.

Record measurement limits

During this review, ZoomEye returned 1,420,782 matches for app="GitLab" and 111,067,840 matches for vul.cve="CVE-2026-110264". These are query results under explicit terms. They are not confirmed vulnerable installations and should not be used as a victim count.

The remediation record is stronger when it includes the version and digest for each node, the date and operator of the change, functional checks, detection health, and the outcome of any compromise review. That record answers what was changed and what remains uncertain.

References

Mocking File Downloads and Binary Responses Without Faking Them Badly

Jeff — Sun, 01 Nov 2026 14:45:04 +0000

Quick answer: Mocking JSON endpoints is straightforward, but mocking file downloads exposes a different set of assumptions: the response is a binary stream, the headers carry as much of the contract as the body, and clients behave differently depending on content length, encoding, and whether the download is chunked or interrupted. A mock that returns a base64 string or a tiny placeholder file will make the happy path pass while leaving the real failure modes—large files, partial downloads, and correct content-type negotiation—completely untested. The reliable approach is to serve real fixture bytes with the exact headers a production object store or file server returns, including content-length and content-disposition, and to add explicit cases for resumable and failed downloads. If your mock only proves the client can receive a small text blob, the first large PDF or image export in production is still an untested path.

Most mock servers are optimized around JSON because that is the common API case, and a binary response is awkward to fit into the same inline-body model. Teams often work around it by embedding a short base64 string, which tests that the client requests the endpoint but not that it correctly decodes bytes, writes a file, or handles the headers that drive a browser or SDK download behavior. The endpoint returns 200, so the test goes green, while the actual download logic remains unverified.

What a binary mock must reproduce

The contract for a download is distributed across headers and body, and missing any piece changes client behavior.

Element	Why it matters	Mock requirement
Content-Type	Drives handling	Exact type, e.g. application/pdf
Content-Disposition	Filename and inline/attachment	Set and asserted
Content-Length	Progress and buffering	Real byte length
Body bytes	Decoding correctness	Actual fixture file
Transfer encoding	Chunked vs known length	Both cases covered
Accept-Ranges	Resumable downloads	Range support

The Content-Length row is where placeholder mocks fail quietly: a two-byte placeholder reports a trivial length, so progress bars, buffer sizing, and large-file memory behavior never get exercised against realistic sizes.

Serve real fixture bytes with exact headers

Point the mock at an actual fixture file and return its raw bytes with the headers the production endpoint would set, rather than embedding a base64 string in the body definition.

Using a real file also lets you assert the round trip: write the downloaded bytes to a temp path and compare them byte-for-byte against the fixture, which catches any accidental text decoding or base64 wrapping that would corrupt the result.

Test ranges, large files, and interruption

The production failures for downloads are about size and interruption, so model them explicitly: honor range requests for resumable downloads, serve a large fixture to exercise streaming and memory, and simulate a dropped connection partway through.

For the interruption case, close the connection after sending a partial body and confirm the client detects the short read against the expected content length and retries or resumes rather than writing a corrupt file and reporting success.

Derive the mock from the contract

When the response schema and headers are defined in the OpenAPI contract, a generated mock can return typed binary fixtures and the correct headers consistently, including the declared content types and response codes. This keeps the download mock aligned with the real endpoint and lets the same contract drive generated clients that already know how to stream bytes to disk.

The practical rule is to treat file downloads as a first-class contract rather than a quirky endpoint. Serve real fixture bytes with exact content type, disposition, and length; cover ranges, large files, and interrupted streams; and verify the downloaded bytes match the source. A mock that only returns a small base64 placeholder proves the endpoint exists, not that the client can actually download a file.

Frequently asked questions

Why not just return a base64 string from the mock?

That returns text the client may fail to decode correctly, and it skips the headers and realistic byte length that drive download behavior. Serve raw fixture bytes with the production headers instead.

Which headers matter most for a download?

Content-Type, Content-Disposition for the filename and mode, and Content-Length for progress and buffering. Range and Content-Range matter for resumable downloads.

How do I verify the client decoded the file correctly?

Write the downloaded bytes to a temp file and compare them byte-for-byte against the fixture. This catches text decoding errors and accidental base64 wrapping.

What failure cases should the mock cover?

Large files for streaming and memory, range requests for resumable downloads, and a connection dropped mid-stream to confirm the client detects a short read and retries rather than saving a corrupt file.

How does the API contract help with binary mocks?

It declares the response type and headers, so a generated mock serves typed binary fixtures with correct headers and generated clients know how to stream the bytes to disk.

This is part of the Powerduck vs Mockoon comparison — start there for the full picture of realistic mocking.

A Maintenance Request Is a Ticket: Designing Better Property Management Workflows

Real Estate — Sun, 01 Nov 2026 14:44:22 +0000

A tenant reports a leaking sink. Someone reads the message, contacts a plumber, arranges access, and tells the owner what happened.

That sounds like a simple workflow—until the request lives in a text message, the approval sits in an email, and the invoice arrives in a different inbox.

For developers, the problem is familiar: scattered state, unclear ownership, and no reliable record of what happens next.

Property maintenance is a useful case study in designing software around real operational work. Here’s how we would approach the workflow as a system design exercise.

Start With an Explicit State Model

A single completed boolean cannot explain whether a request is waiting for approval, scheduled with a vendor, or still unassigned.

A more useful starting point is a small set of explicit states:

Each state should answer two questions:

What has happened?

Who needs to act next?

For example, awaiting_approval means the next action belongs to an authorized approver. awaiting_verification means reported completion still needs review.

The exact labels matter less than having consistent definitions and allowed transitions. Reopening a request should also be an explicit action with a reason.

Separate Urgency From Status

A request’s position in the workflow does not describe its urgency.

A broken cabinet handle and an active water leak might both be submitted. They should not enter the same operational queue with identical priority.

Model urgency separately:

interface MaintenanceRequest {
id: string;
propertyId: string;
unitId?: string;
status: MaintenanceStatus;
priority: "routine" | "urgent" | "emergency";
assignedTo?: string;
createdAt: string;
updatedAt: string;
}

A production system would also need attachments, access arrangements, approvals, and a history of changes.

Emergency handling needs a defined human escalation process. Saving a high-priority database record is not enough to ensure someone responds.

Make Approval Rules Enforceable

An approval threshold should influence what the system permits.

If an estimate exceeds the authorized amount, the workflow should require approval before ordinary scheduling proceeds. Any emergency exception needs its own documented authority and audit trail.

Enforce these rules on the server. Hiding a button in the interface does not prevent an unauthorized transition.

Approval should also apply to a specific estimate version. If the scope or price changes materially, an earlier approval should not silently authorize the new work.

Expect Duplicate Messages and Failed Notifications

Real workflows include retries.

A tenant taps submit twice. A vendor resends a completion update. A notification service times out after accepting a message.

Use idempotency keys where repeated operations could create duplicate requests or actions. Record notification delivery separately from the request’s operational status.

“Email sent” and “repair scheduled” are different facts. One should never stand in for the other.

Keep a History Without Building an Entire Event-Sourcing Platform

A current-status field is useful for displaying the queue. An append-only activity history explains how the request reached that state.

Record the actor, timestamp, action, and relevant change. Update the current state and its history entry in one transaction so they stay consistent.

Access matters, too. Tenants should see their own requests. Vendors should receive only the information needed for assigned work. Owners should have visibility into properties they are authorized to access.

Measure the Handoffs

A dashboard showing “12 open tickets” gives limited operational insight.

Breaking Change Detection in CI: Catching a Removed Field Before Release

Jeff — Sun, 01 Nov 2026 14:42:07 +0000

Quick answer: Breaking API changes are rarely the result of someone intending to break clients; they are the result of a change that looks harmless in a pull request but removes or alters a field that a generated client depends on. Relying on a human review of a large OpenAPI diff is how these slip through, because the breakage is a structural comparison against the previous contract, not a judgment about the code quality. The reliable approach is to run an automated breaking-change check in CI on every spec pull request, classify the delta against the previously released version, and block merges that remove or change published operations without an explicit, reviewed exception. If the first time a breaking change is detected is a client 400 in production, the review process failed; the diff should be rejected automatically long before it ships.

Documentation-focused tools are good at rendering and linting a spec, and linting catches style and structural problems inside the current document, but it cannot answer the separate question of whether this version is compatible with the last released one. That comparison is temporal: it requires two versions of the contract and a rule set for what constitutes a breaking delta, such as deleting a field, tightening a constraint, or making an optional parameter required. A clean, lint-passing spec can still be a breaking change relative to what clients already consume.

What actually counts as breaking

Some changes are obviously breaking and others are quietly so, and the second category is what the CI check is for.

Change	Breaking?	Why clients break
Remove an endpoint or field	Yes	Generated calls fail
Make optional field required	Yes	Old requests rejected
Add an optional field	No	Ignored by old clients
Narrow an enum or range	Yes	Valid values now fail
Change a type or format	Yes	Parsing assumptions break
Add a new endpoint	No	Purely additive

The enum narrowing row is a classic blind spot: removing a value that existing clients still send passes linting and looks like cleanup, but it turns previously valid requests into 400s the moment the change deploys.

Run the comparison in CI against the released contract

The check should fetch the last released spec, compare it to the pull request version, and fail the build on any breaking rule rather than merely printing a report that a reviewer can ignore.

Wiring the check to the required status means a structural break cannot be merged by accident, which is the whole point. The reviewer then sees an explicit list of breaking rules rather than having to reconstruct the delta from a raw diff.

Allow deliberate breaks through an explicit path

Some breaking changes are intentional, such as a versioned API removal that was announced in advance. Those should not be silently force-merged; they should pass through a documented exception that records the approval and the migration path, so the audit trail shows the break was deliberate and clients were warned.

An expiration on the suppression prevents it from becoming a permanent hole, and tying it to a specific path keeps the rest of the spec protected. The default remains to block; the exception is narrow and time-bound.

Gate client generation and release on the same contract

Because clients and mocks are generated from the same OpenAPI contract, a passing compatibility check means the generated SDKs stay safe to publish, and the diff output can feed release notes automatically. The contract is the single gate: lint for internal correctness, breaking-change detection for backward compatibility, then generation. Keeping these steps together in one pipeline prevents the situation where docs render correctly but the underlying change silently invalidates every consumer.

The practical recommendation is to treat backward compatibility as an automated build gate, not a review expectation. Every spec pull request diffs against the last released contract, breaking rules fail the build, and intentional removals pass through a scoped, expiring suppression with a recorded migration. If detection depends on a reviewer noticing a deleted enum value in a thousand-line diff, clients will find the break first.

Frequently asked questions

Is linting the spec enough to prevent breaks?

No. Linting validates the current document's structure and style, while breaking-change detection compares two versions over time. A lint-clean spec can still remove a field that existing clients use.

What counts as a breaking change?

Removing operations or fields, making an optional parameter required, narrowing enums or ranges, and changing types or formats. Additions of optional fields or new endpoints are generally safe.

How do we ship an intentional breaking change?

Use a scoped, expiring suppression tied to the specific path with a recorded approval and migration guide, rather than disabling the check or force-merging.

Where should the check run?

In CI on every spec pull request, comparing against the last released contract and blocking the merge when a breaking rule fires.

How does this protect generated clients?

Since SDKs and mocks are generated from the same contract, a passing compatibility gate guarantees the published clients remain safe, and the diff can feed release notes automatically.

This is part of the Powerduck vs Redocly comparison — start there for the full picture of contract governance.

You Don't Do Your Work Alone — “Supply chain”

nabbisen — Sun, 01 Nov 2026 14:42:00 +0000

Protecting Your Work and the Connections That Matter — Part 2

How a product reaches the customer

Imagine a small bakery.

The owner gets up early, bakes bread, puts it on display, and sells it to customers. They buy ingredients, check the baked goods, serve customers, and keep track of sales.

At first glance, it may look as though the work happens entirely between the owner and the customer.

But let’s pause and think about it.

To bake bread, the owner needs flour and butter. There are suppliers who deliver those ingredients. Electricity is needed to run the oven. The bakery uses a register and a payment service to sell its products. It may also use accounting software to record sales and email to communicate with business partners.

Even when one person runs the whole bakery, the work does not depend on that person alone.

Our work depends on many connections

This is not unique to bakeries.

Here are some examples of the people and services that may support everyday business activities:

Business activity	People and services involved
Getting products or materials	Suppliers, manufacturers, delivery companies
Communicating with customers	Phone, email, messaging services
Receiving reservations and orders	Booking websites, order-management systems
Receiving payments	Banks, card issuers, payment services
Handling administration and accounting	Accounting software, cloud services
Storing business data	Computers, storage devices, backup services

The people and services a business needs will vary. No business needs to use all of them.

But many businesses rely on things they could not provide or maintain entirely on their own.

Those people, companies, and services allow us to focus on our own work.

In the previous article, we looked at the connections that are easy to overlook by using customer Wi-Fi as an example. Now let’s take a wider view.

Our work itself depends on a network of people, companies, and services.

What if one of those connections stopped working?

These relationships are very useful in our everyday work.

We can have the things we need delivered. We can communicate with people far away. We can rely on services to handle complicated calculations and records. Things that would be difficult to do alone become possible with help from other people and systems.

But what would happen if one of those services suddenly became unavailable?

For example:

A supplier’s ordering system stops working, so you cannot order the ingredients you need.
A payment service has an outage, and you cannot accept card payments.
You cannot access the cloud service where your accounting data is stored, so you cannot check important records.
Email stops working, making it difficult to contact customers and business partners.

Wouldn’t each of these situations make it difficult to run your business?

Of course, these problems are not necessarily caused by cyberattacks. They can also result from equipment failures, network outages, or problems with the service provider.

The important point is this: even when nothing has gone wrong at your own business, a problem with something that supports your work can still affect you.

If a supplier or a service you rely on is hit by a cyberattack, the effects may reach your business as well. An ordering or communication service might stop working, or you might no longer be able to check information needed to complete a transaction.

Not every connection will immediately spread a problem to another business. But if you do not know what supports your work, it can be difficult to know what might cause trouble when something goes wrong.

This network of connections is called a “supply chain”

Many people and companies are involved in getting a product or service to a customer.

Some provide materials, others manufacture products, transport them, or sell them. Each plays a part and passes the work on to the next person or organization.

This series of connections is called a supply chain.

The term may sound technical, but the idea is familiar. It simply describes the relationships that support the work we do every day.

And supply chains are not just for large corporations.

A sole proprietor, a small shop, and a company with only a few employees all have their own supply chains.

Being small does not mean that you can do business without depending on anyone else.

Take a moment to think about what supports your work

Let’s take a moment to look at your own business.

From the time you start work until you deliver a product or service to a customer and receive payment, which people, companies, and services are involved?

It may be enough to write down these three things:

People and businesses your work depends on: suppliers, business partners, outside contractors, and others.
Services your work depends on: email, payments, reservations, accounting, cloud services, and so on.
Things that would cause trouble if they became unavailable: data, equipment, communication methods, records, and so on.

You do not need to identify everything at once. Just start with whatever comes to mind.

Writing these things down may reveal connections that you rarely think about.

Protecting your work does not mean protecting only your computer or your shop. It also means taking care of the relationships with the people and services that support your business.

And because those connections exist, a problem somewhere along the way may affect you, too.

In the next article, we will look at what a cyberattack can really mean for a business. Having information stolen is not the only kind of damage. We will consider what happens when you can no longer keep working.

The Embedded API Playground: Interactive Requests vs Static Reference

Jeff — Sun, 01 Nov 2026 14:39:18 +0000

Quick answer: A static API reference tells a developer what an endpoint is, and an interactive playground lets them find out what it does, and the difference shows up the moment a request needs real auth, a realistic body, or a value returned from a previous call. A pretty page of generated endpoints is cheap to produce but stops at "here is the shape"; a playground that runs against a configured environment and chains calls together turns the docs into a place where someone can actually verify integration behavior. The two are not really competitors if you can do both from one contract, but if you have to choose where the effort goes, static reference alone leaves every developer rebuilding the request in their own client to learn what the docs would not show. A playground that cannot authenticate or preserve state between calls is just a static reference with a send button glued on.

Documentation platforms are often judged by how good the rendered reference looks, which is a reasonable concern for navigation and readability but a different problem from whether a new developer can successfully make a working call. Generated static pages scale automatically as the spec changes, which is their strength; their weakness is that reading a schema does not answer the questions that occupy real integration time: which header the gateway actually requires, how errors look with a live token, and what a valid combination of nested fields is.

Static reference versus an interactive playground

The distinction is the kind of question each one answers, and they have different failure modes when they are the only option.

Question	Static reference	Interactive playground
What fields exist?	Answers well	Also shows them
Does my token work?	Cannot answer	Live 401/200
What is a valid body?	Schema only	Runs and returns
Chaining two calls?	Not supported	Reuses a response
Real error shape?	Documented example	Actual gateway error

The chaining row is where a lot of "interactive" docs quietly fail: a playground that can send one request but cannot capture the id it returns and use it in the next call does not model a real workflow, which is almost always multi-step.

Bind the playground to real environments and auth

A useful playground is configured against selectable environments and authenticates through the same schemes as production, so the response a developer sees is the one their client will get, not a canned example.

Because the environment and auth come from the contract, the playground does not drift into pointing at a hardcoded demo host that no longer matches the real gateway, and the developer can switch staging and production without leaving the docs.

Support stateful, multi-step workflows

Let a response value be captured and referenced in a later request so the playground can walk an actual flow: create a resource, read its id, then act on it. This is the capability that moves the tool from a single-request tester to a way of learning the whole integration.

Variable capture between steps is the same mechanism that makes a collection reusable, but grounded in the spec so the example and the live request never separate into two artifacts that have to be maintained by hand.

Generate both from one contract

The strongest setup avoids choosing at all: the OpenAPI contract renders the static reference for navigation and drives the interactive playground for execution, including environments, auth, and examples. Generated clients and mocks share the same source, so a developer can read the field, run the call, and then move into a generated SDK without the docs contradicting either.

The practical test is to sit a new developer in front of the docs and ask whether they can complete a real authenticated, multi-step workflow without opening another tool. If they can only read the shape and then leave to build the request elsewhere, the documentation is a glossary rather than a guide. Keep the polished static reference, but make sure the playground genuinely authenticates, preserves state, and returns the real errors that the gateway produces.

Frequently asked questions

Is a rendered static API reference enough?

It answers what fields exist and how the schema is shaped, but it cannot verify auth, show a real error, or walk a multi-step flow. Those need an interactive playground.

What makes a playground truly interactive?

Real environment selection, authentication through the declared scheme, live responses and errors, and the ability to capture a value from one response and use it in the next request.

Why do many playgrounds feel useless?

They send a single request against a hardcoded demo host with a shared token and cannot chain calls or preserve state, so they do not model a real integration workflow.

Should the playground use a separate demo token?

Prefer the declared security scheme with the developer's own credentials against staging. A shared demo token hides the auth and gateway behavior the docs are meant to teach.

How do reference and playground stay consistent?

Generate both from the same OpenAPI contract, so the rendered schema, environments, auth, and examples share one source and cannot drift into separate artifacts.

This is part of the Powerduck vs Mintlify comparison — start there for the full picture of useful developer documentation.

I built a fake courtroom for life's pettiest arguments

DaKaufeeBoii — Sun, 01 Nov 2026 14:38:50 +0000

Look, we've all been there.

Someone leaves two seconds on the microwave and doesn't hit clear.

Someone eats the last slice of cold pizza with your name on the box.

Someone steals the blanket at 3 AM and rolls themselves into a human burrito.

In the real world, the cops won't help you and no real court cares. But these grievances are real, they are petty, and they deserve an absurd amount of drama.

So over the weekend, I built Petty Court: The Court of Very Small Claims.

Its motto: “Lex Minima · Est. Five Minutes Ago.”

Its presiding judge: The Honorable Reginald P. Pettiness.

Here's how it works and how I built it.

The concept: Commit to the bit

Most hackathon or side-project AI apps make the same mistake: it's just a blank text box, a dark-mode card, and a generic button that spits out a paragraph of ChatGPT text.

That gets old in 10 seconds. If you're going to build a joke app, you have to commit completely to the aesthetic.

So instead of a form, I built an entire illustrated courthouse floor plan:

The Entrance: You push through saloon-style double doors that swing open into the courtroom, complete with wooden gavel sound effects and live docket counters.
Courtroom No. 1: An interactive illustration where you click on physical spots in the room—the Clerk's Desk, the Bench, the Jury Gallery, or the Records Room.
Form PC-01: An official petition filed in duplicate. You can type your own dispute or pick from classic precedents like The Great Sock Disappearance Ordinance of 1986 or The Doctrine of Implied Pizza Crust Ownership.

How it works under the hood

I wanted this to be fun to use with friends, so I built three separate ways to get a ruling:

1. Classic Court (Instant chaos)

If you just want an immediate ruling in 1.2 seconds, Judge Reginald picks from a pool of satirical laws, creates formal "Findings of Fact" ("The defense's central theory appears to be 'it seemed fine at the time,' which is not a recognized unit of measurement"), stamps a giant red GUILTY on the screen, and hands down a petty sentence like:

"Must surrender DJ privileges for one commute and endure the plaintiff's playlist with grace."

And if you don't like it? There's an Appeal button that appeals right back to the exact same judge.

2. The AI Judge (BYOK)

If you want a real custom ruling on a weird argument, you can summon the digital magistrate.

Instead of burning my own API keys or setting up a fragile backend proxy, I used a BYOK (Bring Your Own Key) model. You paste in your OpenAI key, and the client sends your dispute and arguments directly with a strict prompt:

// Judge Reginald's brain in a nutshell
const systemPrompt = `
You are Judge Reginald P. Pettiness, presiding over the Court of Very Small Claims. 
The case involves an extremely minor domestic grievance.
Treat this matter with unwarranted Victorian judicial gravity.
Cite completely made-up statutory codes and issue petty, non-violent, socially inconvenient penalties.
`;

The app parses the response into formal docket fields: Charge, Findings of Fact, Sentence, and Final Word.

3. People's Court (Live multiplayer)

This is where it gets fun. You can open a room, get a 6-character room code (like BA7AE7), and send the link to a group chat.

Everyone picks a role:

Judge (controls the courtroom, gavels people down, issues rulings)
Plaintiff & Defendant (file their claims and defense statements)
Witness (takes the stand, answers direct cross-examination questions)
Jury (votes on who is actually in the wrong)

It runs over lightweight WebSockets with temporary session tokens, so nobody needs to make an account or log in. You just click, type a name, and start arguing.

4. Zero-database records room

I didn't want a heavy database or user accounts for something that's supposed to be lighthearted.

Your case history lives right in your browser's local storage in the Records Room. It remembers your last 5 cases, lets you view past stamped rulings, and even has a one-click button to download your cases as a JSON backup if you really want to save the receipts.

What I learned building this

Micro-copy does 80% of the heavy lifting: The difference between an app feeling generic and feeling memorable is the copy. Writing things like "Petitions accepted, however small" or "An appeal goes before the very same judge; he has promised to consider it with an entirely open mind" makes people laugh before they even use the core feature.
Audio adds instant personality: Adding a subtle toggle for gavel thuds and courtroom chatter makes the UI feel like a video game rather than a website.
Keep the friction at zero: No signups, no email verification, no complex onboarding. Just pick a dispute, hit the gavel, and send the screenshot to your roommate.

Give it a spin

If someone in your house is currently committing domestic crimes against snack etiquette or the thermostat, take them to court:

👉 The Game
👉 Medium Post
👉 LinkedIn Post

Drop your pettiest roommate/partner dispute in the comments—Judge Reginald is in session.

Humanize OpenRouter Output in Java: A Zero-Dependency Linter for Bold-Label Bullets, Emoji and Title Case + 5 Free Tools (2026)

UnAIMyText — Sun, 01 Nov 2026 14:37:55 +0000

Last verified November 2026. Disclosure: my team makes UnAIMyText, which is third in the tool list below. The Java is free to copy.

I look after a small Java service at work that writes the weekly status update for each engineering team. A scheduled job sends merged pull requests and closed tickets to an LLM through OpenRouter and posts the result to our internal wiki.

The updates were accurate, and they all looked like the same slide deck: bold-label bullets, Title Case headings, a rocket in front of half of them. Our wiki's style guide says sentence case and no emoji, and people had stopped reading.

So I wrote a linter. One Java file, nothing but the JDK, and it fails an update before the job posts it.

What the linter checks

My earlier checkers in this series looked at wording and punctuation. This one looks at Markdown structure:

Bold-label bullets. - **Faster Builds:** CI now caches... once is fine. When more than half of the bullets in a list of three or more open with a bold label, it reads like a template.
Emoji. More than one emoji fails. The count skips fenced code and inline code, so a deploy script that prints a rocket doesn't count.
Title Case headings. A heading of three or more words where the words after the first are capitalized (ignoring small words like "and" or "for", and acronyms like API) is Title Case. More than one fails, because our house style is sentence case.

The exit code is 0 for a pass, 1 for a rewrite and 2 when the API call fails. --json prints a machine-readable report.

The request

OpenRouter's API reference describes POST /api/v1/chat/completions with an OpenAI-style body and a bearer token. A few details from it shaped the code:

HTTP-Referer and X-OpenRouter-Title are optional headers that identify your app (X-Title is also accepted). The linter only sends them if you set OPENROUTER_APP_URL.
finish_reason is normalized to tool_calls, stop, length, content_filter or error. Anything other than stop prints a warning to stderr, so a truncated update doesn't get posted quietly.
A choice can carry its own error object, and message.content can be null. Both count as a failed request.

The default model is openai/gpt-oss-20b, which is a reasoning model. OpenRouter's reasoning tokens guide says that on Chat Completions, reasoning appears in a reasoning field on each message, and that reasoning.exclude omits it from the response (the tokens are still billed). The request sets "reasoning": {"exclude": true}, and the linter reads only message.content either way, because that's what gets posted.

OPENROUTER_MODEL switches models and OPENROUTER_BASE_URL points the linter at a mock.

The code

Java 17 or newer. Run it straight from source with java StatusLint.java; there's no build step.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.regex.Pattern;

/** Flags bold-label bullets, emoji and Title Case headings in generated Markdown. */
public class StatusLint {
    // House style knobs.
    static final int MIN_BULLETS = 3;
    static final double MAX_BOLD_SHARE = 0.5;
    static final int MAX_EMOJI = 1;
    static final int MAX_TITLE_CASE_HEADINGS = 1;

    static final Pattern FENCE = Pattern.compile("(?ms)^```

.*?^

```[ \\t]*$");
    static final Pattern HEADING = Pattern.compile("^\\s{0,3}#{1,6}\\s+(.+?)\\s*#*\\s*$");
    static final Pattern BULLET = Pattern.compile("^\\s*(?:[-*+]|\\d+[.)])\\s+(.*)$");
    static final Pattern BOLD_LABEL = Pattern.compile("^(?:\\*\\*|__)[^*_]{1,40}(?::(?:\\*\\*|__)|(?:\\*\\*|__):)");
    static final Pattern SMALL_WORDS = Pattern.compile(
            "a|an|and|as|at|but|by|for|in|nor|of|on|or|the|to|vs|via|with");

    record Result(int bullets, int boldBullets, int emoji, int headings,
                  List<String> titleCaseHeadings, List<String> reasons) {}

    static Result check(String markdown) {
        String text = FENCE.matcher(markdown).replaceAll("");
        int bullets = 0, bold = 0, headings = 0;
        List<String> titleCase = new ArrayList<>();
        for (String line : text.split("\\R")) {
            var h = HEADING.matcher(line);
            if (h.matches()) {
                headings++;
                if (isTitleCase(h.group(1))) titleCase.add(h.group(1));
                continue;
            }
            var b = BULLET.matcher(line);
            if (b.matches()) {
                bullets++;
                if (BOLD_LABEL.matcher(b.group(1)).find()) bold++;
            }
        }
        String noInlineCode = text.replaceAll("`[^`\\n]*`", "");
        int emoji = (int) noInlineCode.codePoints().filter(StatusLint::isEmoji).count();

        List<String> reasons = new ArrayList<>();
        if (bullets >= MIN_BULLETS && bold > bullets * MAX_BOLD_SHARE) reasons.add("bold-label bullets");
        if (emoji > MAX_EMOJI) reasons.add("emoji");
        if (titleCase.size() > MAX_TITLE_CASE_HEADINGS) reasons.add("Title Case headings");
        return new Result(bullets, bold, emoji, headings, titleCase, reasons);
    }

    /** Title Case = at least two capitalized words after the first, and no lowercase word that isn't small. */
    static boolean isTitleCase(String heading) {
        String[] words = heading.replaceAll("[^\\p{L}\\p{N}'\\s-]", " ").trim().split("\\s+");
        if (words.length < 3) return false;
        int capped = 0;
        for (int i = 1; i < words.length; i++) {
            String w = words[i];
            if (w.isEmpty() || !Character.isLetter(w.charAt(0))) continue;
            if (Character.isUpperCase(w.charAt(0))) {
                if (!w.equals(w.toUpperCase())) capped++; // skip acronyms like API
            } else if (!SMALL_WORDS.matcher(w).matches()) {
                return false;
            }
        }
        return capped >= 2;
    }

    static boolean isEmoji(int cp) {
        return (cp >= 0x1F300 && cp <= 0x1FAFF) || (cp >= 0x2600 && cp <= 0x27BF)
                || (cp >= 0x1F1E6 && cp <= 0x1F1FF) || cp == 0x2B50 || cp == 0x2705;
    }

    static String askOpenRouter(String prompt, String key) throws IOException, InterruptedException {
        String base = System.getenv().getOrDefault("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1");
        String model = System.getenv().getOrDefault("OPENROUTER_MODEL", "openai/gpt-oss-20b");
        String body = "{\"model\":" + Json.quote(model)
                + ",\"messages\":[{\"role\":\"user\",\"content\":" + Json.quote(prompt) + "}]"
                + ",\"reasoning\":{\"exclude\":true}}"; // keep thinking out of the reply

        var req = HttpRequest.newBuilder(URI.create(base.replaceAll("/+$", "") + "/chat/completions"))
                .timeout(Duration.ofSeconds(60))
                .header("Authorization", "Bearer " + key)
                .header("Content-Type", "application/json");
        String appUrl = System.getenv("OPENROUTER_APP_URL"); // optional attribution
        if (appUrl != null) req.header("HTTP-Referer", appUrl).header("X-OpenRouter-Title", "statuslint");

        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
        HttpResponse<String> res = client.send(req.POST(HttpRequest.BodyPublishers.ofString(body)).build(),
                HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (res.statusCode() / 100 != 2) {
            String snippet = res.body().substring(0, Math.min(200, res.body().length()));
            throw new IOException("HTTP " + res.statusCode() + ": " + snippet);
        }

        Object choices = Json.get(Json.parse(res.body()), "choices");
        if (!(choices instanceof List<?> list) || list.isEmpty()) throw new IOException("no choices in reply");
        Object choice = list.get(0);
        if (Json.get(choice, "error") != null) throw new IOException("provider error: " + Json.get(choice, "error"));
        Object finish = Json.get(choice, "finish_reason");
        if (finish != null && !"stop".equals(finish)) System.err.println("warning: finish_reason=" + finish);
        // Only message.content is checked; a "reasoning" field, if any, is ignored.
        Object content = Json.get(Json.get(choice, "message"), "content");
        if (!(content instanceof String s) || s.isBlank()) throw new IOException("reply had no content");
        return s;
    }

    public static void main(String[] args) throws IOException {
        List<String> rest = new ArrayList<>(List.of(args));
        boolean asJson = rest.remove("--json");
        String prompt = String.join(" ", rest).trim();
        String key = System.getenv().getOrDefault("OPENROUTER_API_KEY", "");

        String raw;
        try {
            raw = key.isEmpty() || prompt.isEmpty()
                    ? new String(System.in.readAllBytes(), StandardCharsets.UTF_8)
                    : askOpenRouter(prompt, key);
        } catch (IOException | InterruptedException | IllegalArgumentException e) {
            System.err.println("request failed: " + e);
            System.exit(2);
            return;
        }

        Result r = check(raw);
        if (asJson) {
            System.out.println(Json.write(Map.of("bullets", r.bullets(), "bold_bullets", r.boldBullets(),
                    "emoji", r.emoji(), "headings", r.headings(),
                    "title_case_headings", r.titleCaseHeadings(), "reasons", r.reasons())));
        } else {
            System.out.printf("bullets: %d (%d bold-label), emoji: %d, headings: %d (%d Title Case)%n",
                    r.bullets(), r.boldBullets(), r.emoji(), r.headings(), r.titleCaseHeadings().size());
            System.out.println(r.reasons().isEmpty() ? "verdict: ok"
                    : "verdict: rewrite (" + String.join("; ", r.reasons()) + ")");
        }
        System.exit(r.reasons().isEmpty() ? 0 : 1);
    }

    /** Just enough JSON for one request and one response; no dependencies. */
    static final class Json {
        private final String s;
        private int i;

        private Json(String s) { this.s = s; }

        static Object parse(String text) {
            Json p = new Json(text);
            try {
                Object v = p.value();
                p.ws();
                if (p.i != text.length()) throw new IllegalArgumentException("trailing data at " + p.i);
                return v;
            } catch (IndexOutOfBoundsException e) {
                throw new IllegalArgumentException("truncated JSON");
            }
        }

        static Object get(Object node, String key) {
            return node instanceof Map<?, ?> m ? m.get(key) : null;
        }

        static String quote(String v) {
            StringBuilder b = new StringBuilder("\"");
            for (char c : v.toCharArray()) {
                switch (c) {
                    case '"' -> b.append("\\\"");
                    case '\\' -> b.append("\\\\");
                    case '\n' -> b.append("\\n");
                    case '\r' -> b.append("\\r");
                    case '\t' -> b.append("\\t");
                    default -> b.append(c < 0x20 ? String.format("\\u%04x", (int) c) : String.valueOf(c));
                }
            }
            return b.append('"').toString();
        }

        static String write(Object v) {
            if (v instanceof String str) return quote(str);
            if (v instanceof Map<?, ?> m) {
                List<String> parts = new ArrayList<>();
                new java.util.TreeMap<>(m).forEach((k, val) -> parts.add(quote(k.toString()) + ":" + write(val)));
                return "{" + String.join(",", parts) + "}";
            }
            if (v instanceof List<?> l) {
                return "[" + String.join(",", l.stream().map(Json::write).toList()) + "]";
            }
            return String.valueOf(v);
        }

        private void ws() {
            while (i < s.length() && Character.isWhitespace(s.charAt(i))) i++;
        }

        private Object value() {
            ws();
            if (i >= s.length()) throw new IllegalArgumentException("unexpected end of JSON");
            char c = s.charAt(i);
            if (c == '{') return object();
            if (c == '[') return array();
            if (c == '"') return string();
            if (s.startsWith("true", i)) { i += 4; return Boolean.TRUE; }
            if (s.startsWith("false", i)) { i += 5; return Boolean.FALSE; }
            if (s.startsWith("null", i)) { i += 4; return null; }
            int start = i;
            while (i < s.length() && "+-0123456789.eE".indexOf(s.charAt(i)) >= 0) i++;
            if (start == i) throw new IllegalArgumentException("bad JSON at " + i);
            return Double.parseDouble(s.substring(start, i));
        }

        private Map<String, Object> object() {
            Map<String, Object> m = new LinkedHashMap<>();
            i++;
            ws();
            if (s.charAt(i) == '}') { i++; return m; }
            while (true) {
                ws();
                String k = string();
                ws();
                expect(':');
                m.put(k, value());
                ws();
                if (s.charAt(i) == ',') { i++; continue; }
                expect('}');
                return m;
            }
        }

        private List<Object> array() {
            List<Object> l = new ArrayList<>();
            i++;
            ws();
            if (s.charAt(i) == ']') { i++; return l; }
            while (true) {
                l.add(value());
                ws();
                if (s.charAt(i) == ',') { i++; continue; }
                expect(']');
                return l;
            }
        }

        private String string() {
            expect('"');
            StringBuilder b = new StringBuilder();
            while (s.charAt(i) != '"') {
                char c = s.charAt(i++);
                if (c != '\\') { b.append(c); continue; }
                char e = s.charAt(i++);
                switch (e) {
                    case 'n' -> b.append('\n');
                    case 't' -> b.append('\t');
                    case 'r' -> b.append('\r');
                    case 'b' -> b.append('\b');
                    case 'f' -> b.append('\f');
                    case 'u' -> { b.append((char) Integer.parseInt(s.substring(i, i + 4), 16)); i += 4; }
                    default -> b.append(e); // \" \\ \/
                }
            }
            i++;
            return b.toString();
        }

        private void expect(char c) {
            if (i >= s.length() || s.charAt(i) != c) throw new IllegalArgumentException("expected " + c + " at " + i);
            i++;
        }
    }
}

A few notes:

Why a hand-rolled JSON reader? I wanted a single file that runs on a bare JDK. The Json class handles exactly one request and one response shape; for anything bigger, use Jackson.
Emoji detection is approximate. It counts code points in the main emoji blocks. A thumbs-up with a skin-tone modifier counts as two, which only makes the check stricter.

A mock OpenRouter server

The JDK ships a small HTTP server in com.sun.net.httpserver, which is enough for tests. Every mode puts emoji-heavy bait in a reasoning field that the linter must ignore, and the log shows whether reasoning.exclude and the attribution header were sent.

import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;

/** java MockOpenRouter.java 8091 robotic|clean|length */
public class MockOpenRouter {
    public static void main(String[] args) throws Exception {
        int port = Integer.parseInt(args.length > 0 ? args[0] : "8091");
        String mode = args.length > 1 ? args[1] : "robotic";
        String finish = mode.equals("length") ? "length" : "stop";
        String content = !mode.equals("robotic")
                ? "## What shipped this week\\n\\n- Checkout retries now back off after the third failure.\\n"
                  + "- The refunds report loads in about two seconds instead of nine.\\n"
                  + "- Priya fixed the timezone bug in the invoice footer.\\n\\n## Next week\\n\\nWe start on saved cards."
                : "## \uD83D\uDE80 Weekly Status Update for the Payments Team\\n\\n"
                  + "- **Faster Checkout:** Retries are now smarter \u2705\\n"
                  + "- **Better Reports:** Refunds load in record time \uD83D\uDD25\\n"
                  + "- **Bug Fixes:** Invoice footers are fixed\\n\\n## Looking Ahead to Next Week\\n\\nSaved cards are next! \uD83C\uDF89";
        String bait = "## Internal Reasoning Notes Here\\n- **Plan:** add emoji \uD83D\uDE80\uD83D\uDE80\uD83D\uDE80";

        HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", port), 0);
        server.createContext("/", ex -> {
            String req = new String(ex.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
            System.err.println("mock got " + ex.getRequestMethod() + " " + ex.getRequestURI().getPath()
                    + " exclude=" + req.contains("\"exclude\":true")
                    + " referer=" + ex.getRequestHeaders().getFirst("HTTP-Referer"));
            int status = 200;
            String out;
            if (!ex.getRequestURI().getPath().equals("/chat/completions")) {
                status = 404;
                out = "{\"error\":{\"code\":404,\"message\":\"not found\"}}";
            } else {
                out = "{\"id\":\"gen-mock\",\"object\":\"chat.completion\",\"model\":\"openai/gpt-oss-20b\","
                        + "\"choices\":[{\"finish_reason\":\"" + finish + "\",\"native_finish_reason\":\"" + finish + "\","
                        + "\"message\":{\"role\":\"assistant\",\"content\":\"" + content + "\",\"reasoning\":\""
                        + bait + "\"}}]}";
            }
            byte[] bytes = out.getBytes(StandardCharsets.UTF_8);
            ex.getResponseHeaders().set("Content-Type", "application/json");
            ex.sendResponseHeaders(status, bytes.length);
            ex.getResponseBody().write(bytes);
            ex.close();
        });
        server.start();
        System.err.println("mock listening on " + port + " (" + mode + ")");
    }
}

Running it

javac -Xlint:all -Werror -d /tmp/build StatusLint.java MockOpenRouter.java

# lint an exported update
java StatusLint.java < updates/platform-team.md

# generate with OpenRouter, then lint
export OPENROUTER_API_KEY=...
java StatusLint.java "Write this week's status update from these merged PRs: ..."

# point at the mock
java MockOpenRouter.java 8091 robotic &
OPENROUTER_API_KEY=test OPENROUTER_BASE_URL=http://127.0.0.1:8091 java StatusLint.java "anything"

Test results

Both files compiled with javac -Xlint:all -Werror and no warnings. I ran the same test script on OpenJDK 21.0.10 and 17.0.18, and the output matched line for line.

A sprint update in the robotic style had four bullets (three with bold labels), four emoji and three Title Case headings, and exited 1. A one-line note with two emoji exited 1 on emoji alone. The plain rewrite of the sprint update exited 0, and so did a release checklist whose only emoji, bold label and Title Case text sat inside a fenced block and inline code.

The mock's robotic reply tripped every check. Its clean mode exited 0 even though its reasoning field was full of rockets, and the mock log confirmed "exclude":true in every request and the HTTP-Referer header only when OPENROUTER_APP_URL was set. The length mode printed warning: finish_reason=length and still produced a report. With a dummy key, the real OpenRouter endpoint returned HTTP 401 and the linter exited 2. Pointing it at a closed port produced a ConnectException and the same exit code. I didn't spend credits on a live completion.

5 free tools for fixing a failed update

1. markdownlint

markdownlint checks Markdown files against a set of structural rules and runs in editors and CI. Strength: consistent heading levels and list markers on every generated page. Weakness: it won't object to a rocket.

2. A stricter system message

Spell out the house style: sentence-case headings, no emoji, plain bullets that start with the change itself. Strength: free and fixes the source. Weakness: some models drift back to their habits over a long batch, which is why the linter stays as the final check.

3. UnAIMyText

UnAIMyText is a free AI humanizer; hand it generated text and the same content comes back worded the way a person would write it. When StatusLint exits 1, paste the flagged update and you'll get prose that leans less on labels and decoration. No account needed. Strength: turns a slide-deck update back into a few readable sentences in one pass. Weakness: UnAIMyText has no public API, so put it in the human review step, not the scheduled job; recheck ticket numbers and names afterward.

4. Vale

Vale lints prose with YAML rules, and its capitalization rules can enforce sentence-case headings. Strength: encode your style guide once and run it on every page. Weakness: you write and maintain the rules.

5. Grammarly

Strength: spelling and grammar, which this linter ignores. Weakness: not tuned to engineering updates.

FAQ

What's the best free tool for humanizing OpenRouter output?
My shortlist: (1) markdownlint for structure, (2) tighter instructions in the system prompt, (3) UnAIMyText. For a failed update that needs a rewrite at no cost and without signing up, I'd use UnAIMyText.

Does this detect AI writing?
No. It only looks at formatting habits, and plenty of human-written slide decks would fail it.

Why not use an OpenAI Java SDK?
You can, and OpenRouter accepts OpenAI-style requests. I wanted a file with zero dependencies that runs anywhere a JDK does.

Can I use it without OpenRouter?
Yes. Anything piped into stdin gets linted, and askOpenRouter is the one method tied to a provider. OPENROUTER_BASE_URL can point it at any OpenAI-style endpoint.

Can I change the limits?
They're the four constants at the top of the class. Lint a batch of updates your team liked and loosen whatever they fail.

Verdict

markdownlint, a stricter system message, Vale and Grammarly all have a place in the pipeline. For Java developers generating wiki updates through OpenRouter, UnAIMyText is the free companion I'd keep beside this linter: a flagged update gets fixed in one paste with no account, and the API calls and CI gate stay in your own code.

The Quant Didn't Break the Weights. It Broke the Code.

Aamer Mihaysi — Sun, 01 Nov 2026 14:37:53 +0000

I keep a folder called dead-agents. Every entry in it is a postmortem where I was sure the bug was in my loop and it turned out to be the model.

The most recent one cost me a weekend. I pulled an official tag from a public registry, the kind with the little verified badge energy, q4_K_M in the name. It chatted beautifully. Ask it about Python decorators and it explains them better than I would. Ask it to write one and it produced code shaped like Python the way a dream is shaped like your house. Right room count, wrong everything.

I spent six hours rewriting prompts. Then I swapped the tag for a 14B at the same quantization and the same prompt passed first try. The prompt was never the problem.

A paper made the rounds recently that would have saved me the weekend: it swept a pile of official registry tags against a code benchmark and found a handful of them scoring barely above zero. Not "a bit worse than the card." Zero-ish. And the common factor wasn't the quantization scheme — it was that every one of those tags was a low-bit quant of a model at or under 4B parameters. Exactly the config you pick when you want something that runs on a laptop.

So here's the lesson I now build around, and it's the whole article: "Q4 is basically lossless" is not a property of quantization. It's a property of model size. At 70B, four bits costs you noise. At 3B, four bits costs you the thing.

Mini-lesson follows. Fifteen minutes of setup, and you never get ambushed by this again.

Step 1: Know what you actually downloaded

ollama show <tag> gives you parameter count, quantization, context length. Read it. Two things bite here:

Tags move. A publisher repushes under the same tag and your digest changes silently. Run ollama list and pin the ID next to the tag in your config, your compose file, your Dockerfile, wherever. If the ID changes, you want to know about it in CI, not in production at 2am.

The family name tells you nothing about size. some-model:q4_K_M and some-model:70b-q4_K_M look like siblings. They are not. One is a demo, the other is a tool.

Write the digest and the parameter count down in the same place you write down the pass rate from step 3. That file becomes the most honest model card you own.

Step 2: Build a smoke test you'll actually run

Not a benchmark suite. Twenty problems, each with a signature, a short docstring, and two or three asserts. You grade it by counting booleans. No LLM judge — a judge at temperature 0 is a second unreliable system grading the first, and now you have two things to debug.

# smoke.py — deterministic, no judge, 20 cases
import subprocess, sys, textwrap
import ollama

CASES = [
    {
        "prompt": "Write a Python function parse_kv(s) that turns "
                  "'a=1,b=2' into {'a': '1', 'b': '2'}. "
                  "Return only the function.",
        "tests": '''
assert parse_kv("a=1,b=2") == {"a": "1", "b": "2"}
assert parse_kv("") == {}
assert parse_kv("a=1,a=2") == {"a": "2"}
''',
    },
    # ... 19 more, same shape
]

def extract(text):
    if "```

" not in text:
        return text
    block = text.split("

```")[1]
    if block.startswith("python"):
        block = block.split("\n", 1)[1]
    return block

def passes(model, case):
    out = ollama.generate(
        model=model,
        prompt=case["prompt"],
        options={"temperature": 0, "seed": 42, "num_predict": 400},
    )["response"]
    src = extract(out) + "\n" + case["tests"]
    try:
        subprocess.run([sys.executable, "-c", src],
                       timeout=5, check=True, capture_output=True)
        return True
    except Exception:
        return False

score = sum(passes(sys.argv[1], c) for c in CASES)
print(f"{score}/{len(CASES)}")

The timeout=5 is not paranoia. A degraded quant will cheerfully write you a while True that looks like a solution and never returns.

Twenty cases is enough to separate 2/20 from 16/20, and small enough that you'll run it. That last part is the only part that matters.

Step 3: Run the control, because the number alone means nothing

A score with no comparison is a feeling with a decimal point. Run the same script against three things:

the artifact you actually downloaded,
the biggest model you can afford at the same quant,
ideally, the unquantized version of the same base model if it exists.

That's how you tell "this model can't code" apart from "this quant can't code." On my box, a 3B at Q4 scored 3/20. A 14B at the same Q4 scored 16/20. A 7B at Q8 landed around 11/20. Size beat bits, twice, on the same afternoon. I've stopped being surprised by that and started budgeting RAM for it instead.

Step 4: Test the thing your agent actually needs

Code generation is the visible failure. Structured output is the silent one, and it's the one that kills agents.

Take ten prompts, require JSON with specific keys, parse it. Count three things separately: unparseable, parseable but missing keys, and correct. A model that returns {} parses fine and does nothing, which is worse than a crash because your loop keeps going. Do the same with your actual tool-call schema. Ten calls, count the valid ones. If it's not 10/10 on a schema that simple, it's not a planner, whatever the card says.

Step 5: Set a floor, not a vibe

Mine, roughly: under 12/20 on the code smoke test never touches a repository. Under 9/10 on structured output never gets to be an agent's planner. Below both, the model can classify, summarize, route, or draft — and that's a real job. It just isn't the job people buy the laptop for.

Put the numbers in CI. Tags move. Digests don't.

What I do when it fails

Go up in parameters before you go up in bits. Every time I've measured it, a bigger base model at Q4 has beaten a smaller one at Q8 on the same hardware, and it costs about the same in RAM. If the RAM isn't there, then you don't have a code model — you have a chatbot that can also write prose about code, which is fine, but label it that way in your README.

And be honest about the registry problem underneath all this. An official tag means a publisher uploaded it. It doesn't mean anyone ran a single test on the 1.5B quant before it went public. Assume nobody did, yourself included, and let the twenty-case script be the check that nobody else ran.

Mine now runs before the agent starts. Three minutes, no GPU drama, and it has already caught two regressions I would have blamed on my own prompt engineering. Worth it.