docs: explain casing primarily as a parser simplification

[TheLazyCat00]

The documentation overstates identifier casing as a central language foundation. Explain its primary purpose as simplifying parsing and preventing possible ambiguities by enforcing the intended PascalCase/camelCase convention; present readability as a secondary benefit.

Reduce casing's prominence in the foundations overview and README, and correct the design rationale in the foundations and lexical stories. Identifier rules and language semantics are unchanged.

Validation: npx --yes markdownlint-cli2 '**/*.md' passed for all 40 Markdown files; git diff --check passed.

Summary by CodeRabbit

• Documentation
  • Clarified that initial-letter casing distinguishes type names from value names during parsing, including where type expressions could be confused with comparisons.
  • Updated the foundations and lexical guides to describe casing as a parsing aid and readability convention, rather than a standalone foundation.
  • Specified that type names use PascalCase and value names use camelCase.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: zane-lang/coderabbit/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 2542697c-3d8f-4c0c-9cf1-060298e4d10b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: zane-lang/coderabbit/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 92b14006-d4ed-4331-8bac-712c73f95f87

📥 Commits

Reviewing files that changed from the base of the PR and between f73cc01 and 9f32ba6.

📒 Files selected for processing (5)

• README.md
• spec/foundations.md
• spec/lexical.md
• stories/foundations.md
• stories/lexical.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The specification and stories now describe initial identifier casing as a parsing aid that distinguishes type names from value names, including the overlap between type expressions and comparisons. Foundations descriptions remove casing as a semantic commitment and separate it from staged types and strictness.

Changes

Identifier casing documentation

Layer / File(s)	Summary
Specification wording spec/lexical.md, spec/foundations.md, README.md	The lexical specification describes initial casing as a way to distinguish type names from value names during parsing. The foundations specification removes casing as a commitment and refers to the lexical specification. README descriptions no longer list casing as a foundations topic.
Story alignment stories/foundations.md, stories/lexical.md	The foundations story separates casing from staged types and strictness. The lexical story explains casing’s parsing role and distinguishes it from privacy markers.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 9f32b

This PR clarifies documentation without changing executable rules. The reviewed grammar supports the casing distinction, so no actionable merge-blocking risk remains.

Architecture Summary

Architecture risk: 🔵 Low · up to 9f32b

The change affects 3 systems.

Changed systems: spec, stories, README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — spec (service) was modified; 2 changed files map to changed impact.
• observed — stories (service) was modified; 2 changed files map to changed impact.
• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: The foundations document description removes “casing-determines-kind” from its list of cross-cutting commitments.
• observed — Modified behavior in README.md: The foundations story description removes “casing-determines-kind” from its list of topics.
• observed — Modified behavior in spec/foundations.md: The overview’s “Casing determines kind” commitment was removed.
• observed — Modified behavior in spec/foundations.md: Section 4 now frames enforced identifier casing as a parsing aid, refers to lexical.md for the initial-case rule and ambiguities, and links to the lexical story. This replaces the section defining casing as semantic and describing its consequences for type syntax, parameters, and readers.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation change: it presents identifier casing primarily as a way to simplify parsing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request reframes the 'casing determines kind' rule from a core semantic foundation of the language to a practical surface grammar and parsing decision, updating the specification and story documents accordingly. The feedback recommends using British spelling ('organising' instead of 'organizing') in stories/lexical.md to ensure consistency with the rest of the repository.