✅ ## Getting started
✅ ## Import system overview
❌ ## Getting Started
❌ ## Import System Overview

❌ Verbose:
In order to create a domain in DomainLang, you will need to use the Domain keyword followed by a name.

✅ Concise:
Create a domain with the `Domain` keyword and a name:
\`\`\`dlang
Domain Sales {}
\`\`\`

/**
 * Brief one-line description (required).
 * 
 * Longer explanation if needed (optional).
 * Can span multiple paragraphs.
 * 
 * @param paramName - Description of parameter
 * @param options - Configuration options
 * @returns Description of return value
 * @throws {ErrorType} When this error occurs
 * @example
 * ```typescript
 * const result = myFunction('input', { option: true });
 * ```
 */
export function myFunction(paramName: string, options?: Options): Result {
    // Implementation
}

✅ /** Parses a DomainLang document and returns the AST. */
✅ /** Validates that domain names are unique within a namespace. */
✅ /** Resolves cross-references between bounded contexts and domains. */

❌ /** This function parses. */  // Too vague
❌ /** Parse function. */  // Not a sentence
❌ /** TODO: Document this later. */  // Not helping

✅ @param uri - Absolute URI of the document to parse
✅ @param options - Configuration for parsing behavior
✅ @param accept - Validation acceptor for reporting diagnostics

❌ @param uri - The uri  // Redundant
❌ @param options - Options  // Obvious

/**
 * Queries bounded contexts by classification role.
 * 
 * @example
 * ```typescript
 * const coreContexts = query.boundedContexts()
 *     .withRole('Core')
 *     .toArray();
 * ```
 */

/**
 * Represents a domain in the strategic design model.
 * 
 * Domains can be organized hierarchically using the `in` clause.
 * 
 * @example
 * ```dlang
 * Domain Sales in Commerce {
 *     vision: "Sell products online"
 * }
 * ```
 */
Domain:
    'Domain' name=ID ('in' parentDomain=[Domain:QualifiedName])?
    '{' ... '}';

✅ Good:
// Langium requires late binding to resolve circular dependencies
this.indexManager.setLanguageServices(services);

✅ Good:
// Cache computed scopes for O(1) lookup during reference resolution
private scopeCache = new Map<string, Scope>();

❌ Bad:
// Set the name
this.name = name;

❌ Bad:
// Loop through domains
for (const domain of domains) { }

# Project Title

One-sentence description.

## Features

- Feature 1
- Feature 2

## Installation

\`\`\`bash
npm install package-name
\`\`\`

## Quick Start

Minimal working example.

## Documentation

Link to full documentation.

## Contributing

Brief contribution guidelines.

## License

License information.

# Bounded Contexts

A bounded context is an explicit boundary within which a domain model is defined.

## Why Use Bounded Contexts

Bounded contexts help you:
- Manage complexity in large systems
- Define clear ownership boundaries  
- Avoid model conflicts

## Basic Example

\`\`\`dlang
bc OrderContext for Sales {
    description: "Handles customer orders"
}
\`\`\`

See [Domains](/guide/domains) for defining the domain hierarchy.

Learn more about [Context Maps](/guide/context-maps) for mapping relationships.

// ✅ Actionable, specific, helpful
accept('error', `Domain '${domain.name}' duplicates '${existing.name}' defined at line ${existingLine}. Rename one domain or use namespaces to distinguish them.`, {
    node: domain,
    property: 'name'
});

// ✅ Contextual warning with guidance
accept('warning', `Domain '${domain.name}' has no domain vision. Add a vision statement to describe the domain's strategic purpose.`, {
    node: domain,
    property: 'name'
});

// ❌ Vague
accept('error', 'Invalid domain', { node: domain });

// ❌ Blames user
accept('error', 'You forgot to add a vision', { node: domain });

// ❌ No guidance
accept('error', 'Duplicate name detected', { node: domain });

# Documentation updates (no version bump)
docs: update SDK query API documentation
docs(grammar): add JSDoc for domain hierarchy rules
docs(readme): improve installation instructions

# Site documentation (handled by site-maintainer)
docs(site): add context map tutorial