docs: establish Endorphin language documentation baseline

guide/03-namespaces.md

@@ -0,0 +1,65 @@
+# 3. namespace
+
+namespace 是代码归属、组织与检索的单位。系统使用 namespace key 查找索引，取得对应代码段，并形成可见代码视图。
+
+## 3.1 key 格式
+
+```text
+用户名:第一级namespace.后续namespace
+```
+
+key 由一个用户名、一个冒号和至少一个 namespace 路径段组成。路径段之间用点号连接：
+
+| key | 结构 |
+| --- | --- |
+| `alice:shop` | 用户名与一级 namespace |
+| `alice:shop.pricing` | 用户名与两级 namespace |
+| `alice:shop.backend.orders` | 用户名与三级 namespace |
+
+key 中的用户名规则见[用户身份](02-user-identity.md)。namespace 路径段在本文词法草案中使用标识符，详见[词法结构](06-lexical-structure.md)。
+
+## 3.2 最小归属
+
+代码必须同时具有用户和非空 namespace 路径。下列形式缺少必要信息：
+
+| 形式 | 缺少的内容 |
+| --- | --- |
+| `alice` 或 `alice:` | namespace 路径 |
+| `:shop` | 用户名 |
+| `alice.shop.ui` | 用户名与 namespace 的分隔冒号 |
+
+显示名不能替代用户名。代码也不能直接归属于没有 namespace 的用户根层级。
+
+## 3.3 层级语义
+
+用户之下的第一级 namespace 与所有后续层级具有相同语义。`shop` 在位置上类似 repository 那一层，但不构成独立的 repository 或特殊 module 类型。
+
+namespace 路径表示组织关系。路径段名 `ui`、`backend`、`data` 或 `agents` 不自动决定执行位置、数据存储、通信方式或语言阶段。
+
+父子 namespace 的可见性与成员范围需要独立规则；仅凭路径前缀不能认定读取父级一定包含全部子级代码。
+
+## 3.4 可见代码视图
+
+代码以独立代码段存储，索引关联完整 key 与代码段。可见代码视图是根据这些成员关系获得的逻辑代码集合：
+
+```text
+alice:shop.pricing
+    → namespace 索引
+    → 对应的独立代码段
+    → 可见代码视图
+```
+
+视图可以用于阅读和程序处理，不依赖源码文件的物理路径。S3 承担代码段的存储职责；对象键与语言中的 namespace key 是不同概念，详细约定见[代码存储与视图](../appendices/code-storage-and-views.md)。
+
+## 3.5 归属与引用
+
+归属 key 定位当前代码，use key 定位它引用的代码。两者使用同一 key 格式，但承担不同职责：
+
+```text
+当前代码：bob:shop.checkout
+引用目标：alice:shop.pricing
+```
+
+当前代码的 key 由外部上下文提供；引用目标写入正文的 `use` 声明。引用不改变归属，也不自动授予访问权限。下一章说明声明与导入的组织方式。
+
+[上一章：用户身份](02-user-identity.md) · [下一章：程序结构与导入](04-program-structure.md) · [目录](../README.md)