docs: Document naming convention enforcement from PR #245

[Copilot]

PR #245 introduced three identifier schemas (SystemIdentifierSchema, SnakeCaseIdentifierSchema, EventNameSchema) enforcing lowercase snake_case for all machine identifiers across the protocol.

Changes

New Documentation

• content/docs/developers/naming-conventions.mdx - Comprehensive guide covering all three schemas, validation patterns, Field.select() auto-conversion, and migration examples

Updated Core Docs

• README.md - Naming rules in key standards section
• CONTRIBUTING.md - Complete identifier reference table and rationale
• ARCHITECTURE.md - Naming conventions section in package structure
• design-principles.mdx - Added Principle V: Strict Naming Conventions
• terminology.mdx - Machine identifier vs label definitions

Naming Convention Matrix

Type	Pattern	Example	Usage
Machine Identifier	snake_case	crm_account, sales_manager	Objects, fields, roles
Event Name	dot.notation	user.created, order.paid	Events, webhooks
Schema Property	camelCase	maxLength, isRequired	TypeScript properties
Label	Any case	Sales Manager	Display text

Example

// Correct
{
  name: 'sales_manager',      // Machine identifier
  label: 'Sales Manager',     // Display label
  maxLength: 100              // Schema property
}

// Auto-conversion
Field.select(['In Progress', 'Closed Won'])
// → [
//   { value: 'in_progress', label: 'In Progress' },
//   { value: 'closed_won', label: 'Closed Won' }
// ]

All documentation cross-references the identifier schema pages in /docs/references/shared/identifiers/.

Original prompt

拉取请求: #245

基于这个修改更新相关文档

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
spec	Ready	Preview, Comment	Jan 26, 2026 4:44pm

[Copilot]

Pull request overview

Updates documentation to reflect the identifier naming convention enforcement introduced in PR #245 (lowercase identifiers, snake_case for most machine names, dot notation for events), and adds a dedicated developer guide.

Changes:

• Added a comprehensive developer-facing “Naming Conventions” guide covering identifier schemas, examples, and migration notes.
• Updated introduction docs (Terminology, Design Principles) to define machine identifiers vs labels and emphasize strict naming.
• Updated core repository docs (README, CONTRIBUTING, ARCHITECTURE) to reference the new enforcement and schemas.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
content/docs/introduction/terminology.mdx	Adds glossary entries clarifying “Machine Identifier (API Name)” vs “Label”.
content/docs/introduction/design-principles.mdx	Adds a new “Principle V” section to explain why strict naming is enforced and links schema references.
content/docs/developers/naming-conventions.mdx	New detailed naming conventions guide with schema breakdowns, examples, validation, and migration.
content/docs/developers/meta.json	Adds the new naming conventions page to the developers navigation.
README.md	Updates “Key Standards” naming section to reflect snake_case + dot.notation and points to schema implementation.
CONTRIBUTING.md	Expands naming conventions guidance with a reference table and rationale.
ARCHITECTURE.md	Documents identifier schemas within the package overview and adds naming conventions rationale.

[Copilot]

The lucide-react icons are imported but never used in this MDX file. If the docs build runs lint/type-check on MDX, this can fail or add unnecessary bundle weight. Remove the unused import or actually use the icons in the content.

Suggested change

import { AlertTriangle, Check, X } from 'lucide-react';

[Copilot]

The “Incorrect” examples use repeated object keys (multiple name: properties in the same object), which is invalid TypeScript/JavaScript and can confuse readers copying the snippet. Use separate objects (or an array of examples) instead of duplicating keys in one object literal.

Suggested change

	{
	name: 'CrmAccount', // ❌ PascalCase
	name: 'crm-account', // ❌ kebab-case
	name: 'CRM Account', // ❌ Spaces
	name: '_account', // ❌ Leading underscore
	}
	// Role Definition
	{
	name: 'SalesManager', // ❌ PascalCase
	name: 'sales-manager', // ❌ kebab-case
	}
	// Event
	{
	name: 'UserCreated', // ❌ Should use dots
	name: 'User.Created', // ❌ Capital letters
	}
	{ name: 'CrmAccount' } // ❌ PascalCase
	{ name: 'crm-account' } // ❌ kebab-case
	{ name: 'CRM Account' } // ❌ Spaces
	{ name: '_account' } // ❌ Leading underscore
	// Role Definition
	{ name: 'SalesManager' } // ❌ PascalCase
	{ name: 'sales-manager' } // ❌ kebab-case
	// Event
	{ name: 'UserCreated' } // ❌ Should use dots
	{ name: 'User.Created' } // ❌ Capital letters

[Copilot]

The conversion rules claim Field.select() will “ensure valid identifier”, but the current implementation only lowercases, replaces spaces with underscores, and strips invalid chars; it does not guarantee the result starts with a letter or meets the min-length constraints enforced by SnakeCaseIdentifierSchema. Either adjust the wording (conversion may still fail validation for some labels) or update the helper to fully satisfy the schema constraints.

Suggested change

	// 4. Ensure valid identifier
	// 4. Attempt to generate a valid identifier; final validation is enforced by SnakeCaseIdentifierSchema (conversion may still fail for some labels)

[Copilot]

This statement says all machine identifiers must be lowercase snake_case, but the same section introduces event names as dot.notation (and the codebase enforces EventNameSchema for events). Consider rephrasing to “all machine identifiers must be lowercase” and specify snake_case for most identifiers, dot.notation for events.

Suggested change

	**All machine identifiers must be lowercase snake_case.**
	**All machine identifiers must be lowercase.** Most identifiers use `snake_case`; event names use `dot.notation` as defined by the EventNameSchema.

[Copilot]

The “Incorrect” snippet repeats the name key multiple times in a single object literal, which isn’t valid TypeScript/JavaScript and is easy to misread. Use separate objects (or an array of examples) instead.

Suggested change

	{
	name: 'SalesManager', // ❌ PascalCase
	name: 'sales-manager', // ❌ kebab-case
	name: 'Sales Manager', // ❌ Contains spaces
	}
	[
	{
	name: 'SalesManager', // ❌ PascalCase
	},
	{
	name: 'sales-manager', // ❌ kebab-case
	},
	{
	name: 'Sales Manager', // ❌ Contains spaces
	},
	]

[Copilot]

Heading uses “Snake_case” (capital S) but the convention elsewhere is consistently written as snake_case. Update the heading for consistency.

Suggested change

	### Why Lowercase Snake_case?
	### Why lowercase snake_case?

[Copilot]

This summary row states machine identifiers are lowercase snake_case, but events are also machine identifiers and use dot.notation (per the table above and EventNameSchema). Consider rephrasing to “machine identifiers are lowercase” and call out snake_case vs dot.notation.

Suggested change

	| **Strict Naming Conventions** | Machine identifiers are lowercase snake_case. Labels are for humans. |
	| **Strict Naming Conventions** | Machine identifiers are lowercase (snake_case for objects/fields, dot.notation for events). Labels are for humans. |

[Copilot]

This callout says all machine identifiers must be lowercase snake_case, but the same page defines event names as dot.notation and notes SystemIdentifierSchema allows dots. Consider rewording to “all machine identifiers must be lowercase” and then distinguish snake_case vs dot.notation to avoid contradicting the rest of the doc.

Suggested change

	**IMPORTANT**: Violating these naming conventions will cause validation errors. All machine identifiers must be lowercase snake_case.
	**IMPORTANT**: Violating these naming conventions will cause validation errors. All machine identifiers must be lowercase. Use snake_case for identifiers with underscores and dot.notation for event-style identifiers.

[Copilot]

In the Event Name section, the “Invalid” list includes user_created but the note says it’s valid (just discouraged). This is confusing for readers—move it to a “discouraged but valid” list/section or clarify that the schema accepts it even if the convention prefers dots.

Suggested change

	// Valid
	'user.created'
	'order.paid'
	'user.login_success'
	'alarm.high_cpu'
	// Invalid
	'UserCreated' // ❌ Use dots for namespacing
	'user_created' // ⚠️ Valid but discouraged (use dots instead)
	// Valid (preferred)
	'user.created'
	'order.paid'
	'user.login_success'
	'alarm.high_cpu'
	// Discouraged but valid (schema accepts underscores, but prefer dots for namespacing)
	'user_created'
	// Invalid
	'UserCreated' // ❌ Must be lowercase and use dots/underscores

[Copilot]

The doc lists only the regex for these identifier schemas, but the actual Zod schemas also enforce minimum lengths (System/SnakeCase min 2, EventName min 3). Consider documenting the min-length constraints as well so users don’t get unexpected validation failures for short identifiers.

Suggested change

	**Regex**: `/^[a-z][a-z0-9_.]*$/`
	**Constraints**:
	- Regex: `/^[a-z][a-z0-9_.]*$/`
	- Minimum length: `2` characters