docs: core tutorials and context management guide (#197)

[halotukozak]

Summary

• Add core tutorials and context management guide
• Add Phase 2 UAT

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##           master     #303   +/-   ##
=======================================
  Coverage   42.03%   42.03%           
=======================================
  Files          35       35           
  Lines         433      433           
=======================================
  Hits          182      182           
  Misses        251      251           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

🏃 Runtime Benchmark

Benchmark	Base (master)	Current (issue-197-tutorials)	Diff

[Copilot]

Pull request overview

Adds new documentation content to help users learn Alpaca via end-to-end tutorials (JSON parser, expression evaluator, extractors) and a guide explaining lexer/parser context and the between-stages hook.

Changes:

• Added a JSON parser tutorial demonstrating lexer + recursive parser rules.
• Added an expression evaluator tutorial showcasing operator precedence and conflict resolution.
• Added guides for extractor usage and for lexer/parser context management.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 10 comments.

File	Description
docs/_docs/tutorials/json-parser.md	New tutorial walking through implementing a JSON lexer/parser.
docs/_docs/tutorials/extractors.md	New tutorial explaining token/rule extractors plus EBNF helpers.
docs/_docs/tutorials/expression-evaluator.md	New tutorial demonstrating precedence/conflict resolution with a calculator grammar.
docs/_docs/context-management.md	New guide describing LexerCtx/ParserCtx and BetweenStages behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

📊 Test Compilation Benchmark

Branch	Average Time
Base (master)	48.731s
Current (issue-197-tutorials)	58.805s

Result: Current branch is 10.074s slower (20.67%) ⚠️

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

docs/_docs/context-management.md:35

• The example tracks parentheses (Token["("] / pattern for () but the field is named braceDepth, which suggests {} rather than (). Renaming the field or changing the example to track braces would avoid confusion.

case class MyCtx(
  var text: CharSequence = "",
  var braceDepth: Int = 0
) extends LexerCtx

val myLexer = lexer[MyCtx]:
  case "\(" => 
    ctx.braceDepth += 1
    Token["("]

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.