settled-reach/docs/workshops/wiki-review/round1-mellanie.md

Round 1 Response: Mellanie (Librarian)

Topics: 2 (Authoring Conventions / Style Guide), 3 (Environmental Text & Regional Culture)

---

Topic 2: Authoring Conventions — What I Learned Writing monologue-guide.md

What conventions I followed

When I wrote the monologue guide, I had D-028, D-032, and D-035 as formal specs. Those gave me the tag schema and the hard partition rule. What they didn't give me was the authoring workflow — the sequence of decisions a writer makes when sitting down to produce a tagged YAML line. I had to reverse-engineer that from the decisions, and the guide is my attempt to codify it.

Conventions I settled on:

1. Mirror-first drafting. Write the smuggler line and detective line for the same trigger back-to-back. Never write one character's pool in isolation — you lose the dual-lens resonance. The guide demonstrates this with paired examples at every trigger type.

2. Prerequisite-before-text. Decide the knowledge gate first, then write the line. If you write the line first, you'll write something beautiful that doesn't match any valid FactId, and you'll spend an hour figuring out why it can't fire.

3. One-breath rule. If a monologue line takes more than one breath to read aloud, cut it. The player is moving, fighting, or watching NPCs. Monologue competes with gameplay for attention. Three words, not thirty.

4. Tell lines need mechanical notes. Every tell observation line gets a notes field documenting which known_attributes key it updates. Without this, there's no way for implementers to know what the line is supposed to DO to the knowledge graph.

5. ID convention: {location}_{type}_{###}. I documented this in the guide but it needs explicit rules about shorthand (hub vs terminal, bar vs last_shift, corr vs corridor). Right now the guide uses both hub and terminal for the same location. That's a collision waiting to happen.

What I wish had been documented before I started

These are the rules that should be in an explicit style guide:

1. Canonical location shortcodes. Every location needs a single, agreed ID prefix. terminal, bar, corridor — not hub, not last_shift, not corr. One name per location. Put it in a table.

2. Prerequisite reference validation. The guide says "use exact FactId strings from the Fact Catalog" but there's no tooling to enforce this. A writer can typo contraband.ring_exist (missing the s) and nothing catches it until runtime. The style guide should mandate: every prerequisite must reference a FactId, RelationshipState, or EntityKnowledge key that exists in the canonical catalogs. If it doesn't exist, the line is invalid. This needs to be a schema check, not a human check.

3. Access tier defaults by character. The monologue guide documents per-NPC access mapping, but there's no rule for what to do when you're writing a generic line that isn't about a specific NPC. What's the default access tier for a smuggler's idle thought? insider (they're part of the community) or public (the thought has no audience)? I defaulted to insider for smuggler monologue and authority or public for detective monologue, but that's my convention, not a documented one.

4. Situation overlap rules. A line can have multiple situation tags (e.g., [arrival, shift_start]). But when is overlap appropriate vs. redundant? If a line fires on arrival, does it also need shift_start? The guide doesn't address this. My working rule: add multiple situations only when the line is genuinely appropriate for both independently. If removing either situation would make the line feel wrong in that context, don't list it.

5. Mood exclusivity. Can a line have mood: [fond, worried]? Yes — the schema allows it. Should it? Only if the character genuinely feels both simultaneously (contaminated trust is [fond, conflicted] not [fond, worried]). The style guide needs to say: mood lists represent simultaneous emotional states, not alternatives. If you mean "either fond or worried depending on context," write two separate lines.

6. Tag freeform discipline. The tags field is a freeform escape hatch. The guide uses tags like [kael, baseline, pre_contradiction], [ring, operational], [the_friend, contradiction, critical_moment]. Without a controlled vocabulary for freeform tags, every author invents their own. Propose: maintain a living list of approved freeform tags per content domain. Not locked — authors can propose new ones — but reviewed. Otherwise you'll get pre-contradiction, pre_contradiction, precontradiction, and before_contradiction all meaning the same thing.

7. Dual-lens notes format. The dual_lens map is authoring-only, but I found myself writing inconsistent entries. Sometimes a sentence, sometimes a phrase, sometimes a full paragraph. Propose: dual-lens notes are one sentence each, imperative voice. "Reads as operational context for the smuggler." "Reads as investigation data for the detective." Consistent, scannable, quick.

What a new author needs that I can provide

If someone joins tomorrow and needs to write monologue lines for a new NPC, here's the minimum kit:

• The monologue guide (exists, complete for triggers and prerequisites)
• Location shortcode table (needs creating)
• Freeform tag vocabulary (needs creating)
• Dual-lens checklist (exists as "Authoring Checklist" in the guide, but needs the dual-lens note format standardized)
• Voice reference per character (partially exists in NPC profiles; needs extraction into standalone voice cards — 5-10 lines per character showing register, vocabulary, sentence length, what they notice)
• A worked example with annotations (the guide has three full pools; could use a single annotated line-by-line walkthrough explaining every tag choice)

---

Topic 3: Environmental Text & Regional Culture

What environmental text changes based on regional culture

Environmental text is everything the player reads that isn't dialogue or monologue: signs, menus, terminal screens, graffiti, public notices, manifests, door labels, safety warnings, news tickers. This is my domain, and regional culture affects ALL of it.

Things that change per region:

1. Language register of official signage. Krenn System is pragmatic, first-name-primary, blunt. Official signs should reflect this: "Bay 3 - Outbound Freight" not "Outbound Freight Processing Bay 3, Section C." Short. Functional. No institutional padding. A system settled by a different cultural cluster might have more formal signage, honorific address, or multilingual notices.

2. Bar menu items and pricing. "Grain spirit" is Krenn culture. "Ale" is generic. What's the local specialty? What are the food items? Menu text reveals economic class (prices), cultural heritage (dish names), and station infrastructure (what can you grow/import?). Lera's menu should feel Krenn — compact, no-frills, a handful of options that regulars know by heart. A bar on a different station might have fifteen options with descriptions.

3. Graffiti and informal markings. This is where culture bleeds through most. Krenn graffiti would be terse, practical, maybe operational — dock workers leaving notes for each other, complaints about shift schedules, inside jokes that require context. On a station with strong political movements, graffiti might be slogans. On a station with religious heritage, you might see blessings or warnings.

4. Terminal screen content. Commission kiosk displays, freight manifests, public information terminals. The information architecture reflects the culture that built the station. Krenn systems are functional — no branding, minimal graphics, data-dense. A Syndic-influenced system might have corporate branding everywhere. An Unbound-sympathetic station might have privacy warnings on every lattice-connected terminal.

5. Safety notices and legal text. "Unauthorized lattice modification: Category 3 violation" is institutional Commission language. But how a station posts that notice reveals its relationship with the Commission. Krenn: small, regulatory-standard, nobody reads it. A compliant Core system: prominent, well-maintained, multiple languages. A fringe settlement: defaced, covered over, or missing entirely.

6. News ticker / Meridian feed. Headlines reflect both the Reach-wide news cycle AND local editorial voice. Krenn System ticker should feel like a working-class local paper — freight prices, shift schedule changes, sports results, a distant political story filtered through "how does this affect us?" framing. The same headline on a Core system ticker would be written for a different audience entirely.

7. Door labels and wayfinding. Krenn uses shorthand. "B-7" not "Maintenance Corridor B, Section 7." Regulars know where things are. New arrivals get lost. This IS gameplay — the detective navigates an unfamiliar space using terse labels, while the smuggler reads them as operational shorthand.

How this affects my authoring workflow

Current problem: I don't have a regional style brief to write against.

When I wrote the monologue guide examples, I used Krenn culture intuitively — compact names, pragmatic language, industrial atmosphere. But "intuitively" isn't reproducible. If I write the news ticker tomorrow, I need to know:

• What heritage languages leave traces in daily speech? (Do people say "varelse" instead of "thing"? Is there a word for the smell of recycled air that has no English equivalent?)
• What naming conventions do businesses follow? (Is "The Last Shift" a Krenn-style bar name? Or is it too on-the-nose for a culture that actually works shifts?)
• What food and drink items exist? (I can't write a menu without a food vocabulary.)
• What media exists? (Is the news ticker text-only? Images? Video? Audio? This affects my writing format.)
• What slang exists for contraband, for the Commission, for lattice technology? (NPCs need to talk about these things without using dictionary definitions. "Running components" not "transporting unlicensed lattice modifications.")

What I need from Topic 3 outputs:

1. A Krenn System regional brief with naming conventions, slang vocabulary (15-20 terms minimum), food/drink list, media format, and cultural markers.
2. A regional style guide template so that when v0.2 adds a new system, I know exactly what cultural information I need before I can write environmental text for it.
3. An environmental text type catalog — every type of in-world text the player can encounter, with character limits, display rules, and cultural variation notes.

Concrete proposal: Environmental text types for v0.1

Here's what I think we need, with authoring notes:

Text Type	Location	Cultural Variation	Approx. Count
Door/bay labels	All locations	Shorthand style (Krenn = terse)	15-20
Safety notices	Hub, corridors	Commission language + local compliance level	5-8
Terminal screens	Commission kiosk, hub manifests	Data density, branding	8-12
Bar menu	The Last Shift	Food/drink names, prices, cultural flavor	1 (the menu)
Graffiti	Corridors, bar restroom	Informal voice, cultural markers, operational notes	10-15
News ticker headlines	Bar, hub, kiosk	Local editorial voice, Reach-wide vs. local mix	15-20 per cycle
Public notices	Hub, bar	Regulatory + community tone	5-8
Freight manifests	Hub	Institutional format, discrepancy-visible design	3-5 templates

Total: ~65-90 environmental text items for v0.1. Each one needs the regional brief to write correctly. The brief is my blocking dependency.

Environmental text and the dual-lens

Environmental text is the one content type that works identically for both characters — same sign, same menu, same terminal screen. But the monologue ABOUT that text differs per character:

• Sign: "Bay 7 - Offline (Maintenance)"
  • Smuggler monologue: "Bay 7's dark. Voss cleared it for the run tonight."
  • Detective monologue: "Bay 7 offline for maintenance. Third time this month. Checking the maintenance log."

The environmental text itself is culturally authored once. The character-specific reading lives in monologue. This is the most efficient content type to produce — and the one that benefits most from a regional brief, because every sign and screen is an implicit worldbuilding detail.

---

Summary of Proposals

1. Create a location shortcode table — one canonical ID prefix per location, enforced in all YAML content.
2. Create a freeform tag vocabulary — living list, reviewed, prevents divergent naming.
3. Standardize dual-lens note format — one sentence per character, imperative voice.
4. Extract voice cards per character — 5-10 reference lines per playable character showing voice register, vocabulary, and perspective.
5. Build prerequisite validation into the content pipeline — schema check against fact catalog, not human review.
6. Prioritize the Krenn System regional brief — blocking dependency for all environmental text authoring.
7. Define the environmental text type catalog — what types exist, where they appear, character limits, cultural variation rules.
8. Standardize mood list usage — simultaneous states only, not alternatives.

Every one of these is a "figured it out by doing, wish it had been written down" problem. The style guide should save the next writer the same discovery process.