HL — Human Layer System Grammar v1.0

A spatial grammar for making any physical environment machine-readable and human-navigable.

Purpose

“I just want to know where my shit is.”

That’s it. That’s the whole problem this solves.

HL is not an app. It is not a platform. It is a grammar — a set of rules for assigning addresses to physical spaces and the things inside them. Once you speak the grammar, any human, any AI, any scanner, any automation system can understand your space without a manual, without onboarding, and without a proprietary database.

If you know a street address, you already understand HL.

Core Philosophy

Human-first. AI-assisted. Recoverability over perfection.

The system must work when the power is out, when the app doesn’t load, when you hand a printed card to a first responder. A photo, a printed label, and a working brain are the minimum viable tools. Everything digital is an enhancement, not a dependency.

Three principles that never bend:

1. The physical label is the source of truth. If the database disagrees with the label on the wall, the label wins until a human decides otherwise.
2. Friction is the enemy. Any rule that makes the system harder to use than no system is a bad rule.
3. You can only drop from the left. Shortening is allowed. Skipping the middle is not.

The Address Format

Every location in your environment gets one address. The format is:

[STRUCT]-[ZONE]-[ANCHOR][COL]-[LEVEL][DEPTH]

That’s it. Six segments. Read left to right, broad to specific.

Segment Reference

Anchor Key

Full Example

SH-MM-S3-A1

Decoded: Shop → MaxOMess zone → South wall → Column 3 → Bottom shelf → Surface level (visible)

Regex Validator (v5.3)

^([A-Z]{2})-([A-Z]{2,3})-([NSEWMFC][1-9])-([A-T])([0-9])$

Counting Rules (Immutable)

These never change regardless of how the space is oriented or what’s in it.

• Horizontal: Left → Right. Column 1 is always the far left of the unit or wall.
• Vertical: Bottom → Top. Level A is always the lowest shelf or position.
• Depth: Front → Back. Depth 0 is always the surface you can see.
• Mobile carts: Position 1 is always the Northwest corner. Count clockwise.

Why bottom-up? Because you can always add a shelf on top and continue the alphabet. You cannot add a shelf at the bottom without renumbering everything above it.

The Sub-Zone Rule

When a smaller space shares walls and access with a parent zone — a closet inside a bedroom, a pantry inside a kitchen — add C to the parent code.

Use only for physically connected spaces. Independent rooms get their own 2-letter code.

Code Shortening Rules

The full canonical address always lives in the database and the QR code payload. What gets printed on a physical label is a display address — and it can be shortened as long as you only drop from the left.

Three Display Tiers

The one hard rule: You can drop STRUCT or STRUCT-ZONE from the left. You cannot drop segments from the middle. S3-A1 is valid. SH-S3-1 is not.

The address format itself is the identifier. You do not need a prefix or logo mark to signal that an address is an HL address. The structure is unmistakable.

The Three Identity Layers

Every physical item in the system has three pieces of identity that work together:

All three together = full traceability. Any one alone = partial traceability. The system works at whatever level of completeness you have — you don’t need all three to start.

Item Naming: The Noun-First Rule

Every item name starts with its root category noun. This is not optional. It is what makes the inventory searchable and AI-parsable without a thesaurus.

Format: ROOT-TYPE-DETAIL-SPEC

The Five Root Nouns

These are the only five top-level categories. If an item does not map to one of them, the answer is not to add a sixth — it is to figure out which of the five it actually is.

Color Coding

Color provides instant visual category identification before anyone reads a label.

Hard rule — not overridable: Red is reserved for POWER, ELECTRICAL, and DANGER across all deployments. This aligns with universal industry standards and keeps people safe.

Everything else is a recommended default. If your environment uses a different color convention, document your local override on your context card. The system stays internally consistent as long as your override is documented.

The Scan-Scan Workflow

Every location has a QR code. Every vessel has a QR code. The check-in workflow is:

1. Scan the location — “I am at SH-MM-S3-A1”
2. Scan the item — “This is MS-013”
3. Result: Database records MS-013 is at SH-MM-S3-A1

Two scans. No typing. No app navigation. This is the same logic warehouse management systems use at industrial scale, applied at home scale.

The same workflow works in reverse for check-out. Scan location, scan item, item is marked as removed from that location.

The Context Card

Every zone should have a printed context card. This is the portable brain of the system.

A context card contains:

• Zone identifier and human-readable name
• Compass orientation diagram
• Column and level reference grid
• QR code linking to the zone’s wiki page
• List of vessels currently assigned to this zone

The context card is what makes the system work offline, for visitors, and for first responders. Photo it. Any LLM with vision can parse the entire space from a single image.

The context card is the viral feature. Hand it to anyone and they can navigate your space without explanation.

Vessel Registry

Vessels are physical containers that move. They are not fixed to a location — they travel between HL addresses and carry kits or materials with them.

A vessel’s current location is a database field, not part of its ID. The ID is permanent. The location updates when it moves.

What Does Not Change

These rules are the constitution. They survive software changes, storage layout changes, AI changes, and ten years of use.

• The six-segment address format
• Left-to-right column counting
• Bottom-to-top level counting
• Front-to-back depth counting
• Mobile cart Northwest-start orientation
• The five root nouns
• Red = power/danger only
• Drop from the left only
• Physical label wins over database in a conflict

What Can Change

These are defaults and recommendations. Adapt them to your environment.

• Structure and zone codes — define your own two-letter codes
• Color assignments (except red)
• Display tier in use on labels
• Vessel prefix naming conventions
• Context card visual design
• Wiki page structure and tooling

The Minimum Viable Deployment

You do not need a server, a scanner, or a QR printer to start. The minimum deployment is:

1. Pick a zone
2. Assign it a code
3. Write the code on a piece of tape
4. Put the tape on the shelf

That’s it. The system is running. Everything else — QR codes, wiki pages, Home Assistant integration, AI agents — is an upgrade layer