feat(constants): implement literal constants with lexical scope

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2 files changed, 40 insertions, 1 deletions

diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md
index b32b7bd..328fd70 100644
--- a/doc/language/cpsc-language-overview.7.md
+++ b/doc/language/cpsc-language-overview.7.md
@@ -22,6 +22,7 @@ The compiler extensions TRY/CATCH/ENDTRY and THROW support anonymous exceptions
 
 # KEYWORDS
 
+- [cpsc-keyword-constant(7)](keyword/cpsc-keyword-constant.7.md): declare a named literal with block scope.
 - [cpsc-keyword-declare(7)](keyword/cpsc-keyword-declare.7.md): declare variables and arrays.
 - [cpsc-keyword-input(7)](keyword/cpsc-keyword-input.7.md): read a value from standard input.
 - [cpsc-keyword-output(7)](keyword/cpsc-keyword-output.7.md): print values to standard output.
@@ -66,7 +67,7 @@ Closing and auxiliary keywords are documented with their main constructs: THEN/E
 
 # UNSUPPORTED FEATURES
 
-CONSTANT, DATE, SET types and DEFINE, random-file operations (RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, INPUT into array elements or fields, string escapes, whole-array assignment or return, array fields, and class methods/constructors/destructors/inheritance (NEW/INHERITS/SUPER).
+DATE, SET types and DEFINE, random-file operations (RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, INPUT into array elements or fields, string escapes, whole-array assignment or return, array fields, and class methods/constructors/destructors/inheritance (NEW/INHERITS/SUPER).
 
 The individual pages note relevant differences from the Cambridge 2026 pseudocode guide. This manual describes the compiler's current support.
 
diff --git a/doc/language/keyword/cpsc-keyword-constant.7.md b/doc/language/keyword/cpsc-keyword-constant.7.md
new file mode 100644
index 0000000..abc39cf
--- /dev/null
+++ b/doc/language/keyword/cpsc-keyword-constant.7.md
@@ -0,0 +1,38 @@
+% CPSC-KEYWORD-CONSTANT(7)
+
+# NAME
+
+cpsc-keyword-constant - declare a named literal value
+
+# SYNOPSIS
+
+```text
+CONSTANT identifier = literal
+```
+
+# DESCRIPTION
+
+Declare a read-only value whose type is inferred from its literal: INTEGER, REAL, BOOLEAN, CHAR, or STRING. A negative integer or real literal is allowed. As required by the Cambridge guide, variables, other constants, expressions, casts, and function calls cannot initialize a CONSTANT.
+
+A constant is visible from its declaration to the end of its enclosing block. A top-level constant is also available in functions and procedures defined after its declaration. Functions do not inherit constants from another function or from an enclosing statement block.
+
+Inner blocks may shadow outer names; leaving a block restores bindings hidden by constants or hiding constants. Each IF branch, loop body, TRY body, CATCH body, and CASE branch has its own constant scope. Ordinary variables otherwise retain their existing function scope. A declaration in the same scope cannot reuse a constant name, and a constant cannot reuse a variable or parameter name in that scope. Type names and enumerator names remain reserved; top-level constants cannot reuse function names.
+
+Constants may be read in expressions, used as CASE labels or array bounds, and passed BYVAL. Assignment, INPUT, READFILE targets, FOR control variables, BYREF arguments, and taking the address of a constant are rejected.
+
+# EXAMPLE
+
+```text
+CONSTANT HourlyRate = 6.50
+CONSTANT DefaultText = "N/A"
+OUTPUT HourlyRate, DefaultText
+IF TRUE THEN
+    CONSTANT HourlyRate = 8.00
+    OUTPUT HourlyRate
+ENDIF
+OUTPUT HourlyRate
+```
+
+# SEE ALSO
+
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-case(7)](cpsc-keyword-case.7.md).