freelang-editor 11.7.4

package/docs/API.md

@@ -0,0 +1,380 @@
+# FreeLang v11 — stdlib API
+
+> Auto-generated by `scripts/gen-stdlib-docs.js` (2026-04-19). Do not edit by hand.
+
+## Modules
+
+- [agent](#agent) (24 functions)
+- [collection](#collection) (25 functions)
+- [crypto](#crypto) (35 functions)
+- [data](#data) (22 functions)
+- [db](#db) (14 functions)
+- [error](#error) (7 functions)
+- [feed](#feed) (7 functions)
+- [file](#file) (14 functions)
+- [http-server](#http-server) (26 functions)
+- [http](#http) (7 functions)
+- [mariadb](#mariadb) (6 functions)
+- [markdown](#markdown) (3 functions)
+- [resource](#resource) (29 functions)
+- [shell](#shell) (8 functions)
+- [time](#time) (34 functions)
+- [workflow](#workflow) (14 functions)
+
+---
+
+## agent
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `agent_create` | name | AgentState |
+| `agent_set` | agent key value | AgentState (immutable update) |
+| `agent_get` | agent key | any |
+| `agent_update` | agent updates | AgentState (merge multiple keys) |
+| `agent_steps` | agent | number |
+| `agent_status` | agent | string |
+| `agent_done` | agent | boolean |
+| `agent_add_tool` | agent toolName fn | AgentState |
+| `agent_call_tool` | agent toolName ...args | any |
+| `agent_tools` | agent | [string] (list registered tool names) |
+| `agent_push_history` | agent entry | AgentState |
+| `agent_history` | agent | [AgentHistoryEntry] |
+| `agent_history_last` | agent n | [AgentHistoryEntry] (last n entries) |
+| `agent_history_type` | agent type | [AgentHistoryEntry] (filter by type) |
+| `plan_create` | steps | Plan |
+| `plan_next` | plan | string | null (current step or null if done) |
+| `plan_advance` | plan result | Plan (mark current step done, move to next) |
+| `plan_done` | plan | boolean |
+| `plan_progress` | plan | number (0.0 - 1.0) |
+| `plan_results` | plan | {step: result} |
+| `observe` | key value context | context (accumulate observations) |
+| `summarize` | context | string (human/AI readable summary of context) |
+| `context_create` |  | {} (empty context) |
+| `context_merge` | ctx1 ctx2 | context |
+
+## collection
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `arr_flatten` | arr | [any]  (flatten one level deep) |
+| `arr_flatten_deep` | arr | [any]  (flatten all levels) |
+| `arr_zip` | arr1 arr2 | [[a,b]]  (zip two arrays into pairs) |
+| `arr_unique` | arr | [any]  (deduplicate, preserves order) |
+| `arr_chunk` | arr size | [[any]]  (split into chunks of size) |
+| `arr_take` | arr n | [any]  (first n elements) |
+| `arr_drop` | arr n | [any]  (all but first n elements) |
+| `arr_sum` | arr | number |
+| `arr_avg` | arr | number |
+| `arr_min` | arr | number |
+| `arr_max` | arr | number |
+| `arr_group_by` | arr key | {key: [items]}  (group objects by a key) |
+| `arr_sort_by` | arr key | [any]  (sort objects by a key, ascending) |
+| `arr_sort_by_desc` | arr key | [any]  (descending) |
+| `arr_count_by` | arr key | {key: count}  (count by key value) |
+| `arr_pluck` | arr key | [any]  (extract field from each object) |
+| `arr_index_by` | arr key | {key: item}  (index objects by unique key) |
+| `retry` | n fn | any  (call fn(), retry up to n times on error) |
+| `retry_silent` | n fn | any|null  (retry n times, return null on final failure) |
+| `memoize` | fn | fn  (return memoized version of fn, keyed by JSON args) |
+| `once` | fn | fn  (return version of fn that only executes once) |
+| `tap` | value fn | value  (call fn(value) for side effects, return value unchanged) |
+| `range` | start end | [number]  (inclusive start, exclusive end) |
+| `range_step` | start end step | [number] |
+| `repeat` | n value | [value]  (array of n copies of value) |
+
+## crypto
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `sha256` | str | string (hex digest) |
+| `sha256_short` | str | string (first 8 chars, useful as short ID) |
+| `md5` | str | string (hex digest, for checksums only) |
+| `sha1` | str | string |
+| `hmac_sha256` | key msg | string (hex digest) |
+| `hash_eq` | hash1 hash2 | boolean (timing-safe compare) |
+| `base64_encode` | str | string |
+| `base64_decode` | str | string |
+| `base64url_encode` | str | string (URL-safe, no padding) |
+| `hex_encode` | str | string |
+| `hex_decode` | hex | string |
+| `random_bytes` | n | string (hex, n bytes of randomness) |
+| `random_int` | min max | number (inclusive) |
+| `random_float` |  | number (0.0 - 1.0) |
+| `uuid_v4` |  | string (random UUID) |
+| `uuid_short` |  | string (8-char short ID from random bytes) |
+| `uuid_from_str` | str | string (deterministic ID from string content) |
+| `is_uuid` | str | boolean |
+| `regex_match` | str pattern | boolean |
+| `regex_match_i` | str pattern | boolean (case insensitive) |
+| `regex_find` | str pattern | string|null (first match) |
+| `regex_find_all` | str pattern | [string] (all non-overlapping matches) |
+| `regex_replace` | str pattern replacement | string |
+| `regex_replace_first` | str pattern replacement | string (only first match) |
+| `regex_extract` | str pattern | [string] (capture groups of first match) |
+| `regex_extract_all` | str pattern | [[string]] (all matches with groups) |
+| `regex_split` | str pattern | [string] |
+| `regex_count` | str pattern | number (count of matches) |
+| `extract_json` | str | any|null  (extract first JSON object/array from text) |
+| `extract_code` | str lang | string|null  (extract code block from markdown) |
+| `extract_emails` | str | [string] |
+| `extract_urls` | str | [string] |
+| `extract_numbers` | str | [number] |
+| `is_email` | str | boolean |
+| `is_url` | str | boolean |
+
+## data
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `json_get` | obj path | any  (dot-path access: "user.name" or "items.0") |
+| `json_set` | obj path value | object (immutable update, returns new obj) |
+| `json_merge` | obj1 obj2 | object (shallow merge, obj2 wins on conflict) |
+| `json_deep_merge` | obj1 obj2 | object (deep recursive merge) |
+| `json_keys` | obj | [string] (get keys of object) |
+| `json_vals` | obj | [any] (get values of object) |
+| `json_parse` | str | object (parse JSON string to object) |
+| `json_str` | obj | string (serialize to JSON string) |
+| `json_stringify` | obj | string (alias for json_str) |
+| `json_pretty` | obj | string (pretty-print JSON) |
+| `json_has` | obj key | boolean (check if key exists) |
+| `json_del` | obj key | object (delete key, returns new obj) |
+| `csv_parse` | str | [[string]] (parse CSV string to rows) |
+| `csv_write` | rows | string (serialize rows to CSV string) |
+| `csv_header` | rows | [string] (get first row as header) |
+| `csv_to_objects` | rows | [{header: value}] (rows to named objects) |
+| `str_template` | template vars | string  ({key} → value substitution) |
+| `str_lines` | str | [string] (split into lines) |
+| `str_join_lines` | lines | string |
+| `str_trim` | str | string |
+| `str_words` | str | [string] (split by whitespace) |
+| `str_count` | str sub | number (count occurrences of sub in str) |
+
+## db
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `db_get` | collection id | data or null |
+| `db_all` | collection | array |
+| `db_put` | collection id data | saved data |
+| `db_delete` | collection id | boolean |
+| `db_project` | name | project data or null  (kimdb shorthand) |
+| `db_projects` |  | project list |
+| `db_query` | dbPath sql params | rows (JSON array) |
+| `db_exec` | dbPath sql [params] | stdout string |
+| `db_insert` | dbPath table data | true |
+| `db_update` | dbPath table data where | true |
+| `db_delete_row` | dbPath table where | true |
+| `db_count` | dbPath table | number |
+| `db_tables` | dbPath | string[] |
+| `db_create` | dbPath sql | true  (CREATE TABLE ...) |
+
+## error
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `error_message` | err | string (get error message) |
+| `error_type` | err | string (get error type/name) |
+| `is_error` | value | boolean (check if value is an error) |
+| `create_error` | message | error (create an error object) |
+| `create_typed_error` | type message | error (create a typed error) |
+| `error_stack` | err | string (get error stack trace) |
+| `with_fallback` | try_fn fallback_fn | any (execute try_fn, fallback on error) |
+
+## feed
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `rss_feed` | meta items | <?xml ... <rss>...</rss> |
+| `atom_feed` | meta items | <?xml ... <feed>...</feed> |
+| `sitemap_xml` | baseUrl routes | <?xml ... <urlset>... |
+| `robots_txt` | options | "User-agent: * ..." |
+| `jsonld_article` | article | <script type="application/ld+json">...</script> |
+| `jsonld_breadcrumb` | items | schema.org BreadcrumbList |
+| `jsonld_organization` | org | schema.org Organization |
+
+## file
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `file_read` | filePath | string (read file content) |
+| `file_write` | filePath content | boolean (write content to file) |
+| `file_exists` | filePath | boolean (check if file exists) |
+| `file_delete` | filePath | boolean (delete file) |
+| `file_append` | filePath content | boolean (append content to file) |
+| `file_copy` | src dest | boolean (copy file) |
+| `dir_create` | dirPath | boolean (create directory) |
+| `dir_list` | dirPath | [string] (list directory contents) |
+| `dir_delete` | dirPath | boolean (delete directory - must be empty) |
+| `file_size` | filePath | number (get file size in bytes) |
+| `file_is_file` | filePath | boolean (check if path is a file) |
+| `file_is_dir` | filePath | boolean (check if path is a directory) |
+| `file_mtime` | filePath | number (get modification time as timestamp) |
+| `file_ctime` | filePath | number (get creation time as timestamp) |
+
+## http-server
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `server_get` | path handlerName | null |
+| `server_post` | path handlerName | null |
+| `server_put` | path handlerName | null |
+| `server_patch` | path handlerName | null |
+| `server_delete` | path handlerName | null |
+| `server_start` | port | string |
+| `server_stop` |  | null |
+| `server_json` | obj | response object |
+| `server_text` | text | response object |
+| `server_status` | code body | response object |
+| `server_wait_respond` | promise | response object (비동기 응답 대기) |
+| `server_req_body` | req | string |
+| `server_req_query` | req [key] | object or string |
+| `server_req_header` | req name | string |
+| `server_req_param` | req name | string |
+| `server_req_method` | req | string |
+| `server_req_path` | req | string |
+| `server_req_id` |  | string | null (현재 요청 ID) |
+| `server_hold_response` | reqId | null (응답 보류) |
+| `server_send_held` | reqId status body | boolean (보류된 응답 전송) |
+| `server_on_upgrade` | fnName | null (WS upgrade 핸들러 등록) |
+| `server_on_ws_message` | fnName | null (클라이언트 WS 메시지 핸들러) |
+| `server_on_ws_close` | fnName | null (클라이언트 WS 종료 핸들러) |
+| `ws_send_to_client` | sessionId data [isBinary] | boolean |
+| `ws_close_client` | sessionId [code] | null |
+| `server_req_session_id` | req | string | null |
+
+## http
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `http_get` | url | string |
+| `http_post` | url body | string |
+| `http_put` | url body | string |
+| `http_delete` | url | string |
+| `http_status` | url | number |
+| `http_json` | url | object |
+| `http_header` | url header | string |
+
+## mariadb
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `mariadb_exec` | db sql [params] | raw output string (INSERT/UPDATE/DELETE/CREATE) |
+| `mariadb_query` | db sql [params] | rows[] (SELECT) |
+| `mariadb_one` | db sql [params] | first row or null |
+| `mariadb_health` |  | true if server reachable |
+| `mariadb_databases` |  | list of database names |
+| `mariadb_tables` | db | list of table names in given db |
+
+## markdown
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `markdown_to_html` | md | html string |
+| `markdown_frontmatter` | md | { fm: {...}, body: "..." } |
+| `markdown_render_full` | md | { fm, html } |
+
+## resource
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `res_cpu_load` |  | [1m, 5m, 15m] |
+| `res_cpu_count` |  | number |
+| `res_cpu_model` |  | string |
+| `res_cpu_pct` |  | number (1-min loadavg based, avoids busy wait) |
+| `res_mem` |  | {total_mb, used_mb, free_mb, buffers_mb, cached_mb, available_mb} |
+| `res_mem_pct` |  | number (used %) |
+| `res_disk` |  | DiskInfo[] |
+| `res_disk_usage` | path | {total_gb, used_gb, avail_gb, use_pct} |
+| `res_procs` |  | ProcessInfo[]  (top 20 by CPU) |
+| `res_find_proc` | name | ProcessInfo[]  (search by name substring) |
+| `res_proc_exists` | name | boolean |
+| `res_proc_pid` | name | number | null |
+| `res_proc_count` | name | number  (how many instances running) |
+| `res_ports` |  | PortInfo[]  (all listening ports) |
+| `res_port_used` | port | boolean |
+| `res_port_info` | port | PortInfo | null |
+| `res_find_free_port` | start end | number | null  (first free port in range) |
+| `res_net` |  | NetInterface[] |
+| `res_hostname` |  | string |
+| `res_uptime_s` |  | number  (system uptime in seconds) |
+| `res_pm2_list` |  | ServiceInfo[] |
+| `res_pm2_find` | name | ServiceInfo | null |
+| `res_systemd_status` | name | ServiceInfo |
+| `res_kimdb_project` | name | Record | null  (query local kimdb) |
+| `res_kimdb_projects` |  | Record[]  (all projects) |
+| `res_kimdb_health` |  | boolean |
+| `res_snapshot` |  | ResourceSnapshot  (complete server state, ~1s) |
+| `res_snapshot_report` | snapshot | string  (human/AI readable) |
+| `res_health_check` |  | {ok, warnings, errors} |
+
+## shell
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `shell` | cmd | string (run command, return stdout) |
+| `shell_status` | cmd | number (run command, return exit code) |
+| `shell_ok` | cmd | boolean (returns true if exit code is 0) |
+| `shell_pipe` | cmd1 cmd2 | string (pipe output of cmd1 into cmd2) |
+| `shell_capture` | cmd | {stdout, stderr, code} (capture all output) |
+| `shell_exists` | program | boolean (check if a program is in PATH) |
+| `shell_env` | varname | string (get environment variable) |
+| `shell_cwd` |  | string (current working directory) |
+
+## time
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `now` |  | number (current timestamp ms) |
+| `now_ms` |  | number (ms since epoch, always returns number) |
+| `now_iso` |  | string (ISO 8601) |
+| `now_unix` |  | number (seconds since epoch) |
+| `time_diff` | t1 t2 | number (ms, positive if t2 > t1) |
+| `time_since` | ts | number (ms elapsed since ts) |
+| `time_ago` | ts | string (human-readable: "3s ago", "2m ago", "1h ago") |
+| `date_parts` | ts | {year,month,day,hour,min,sec,ms,weekday} |
+| `date_add` | ts unit n | number  (unit: "ms"|"s"|"m"|"h"|"d") |
+| `sleep_ms` | ms | void  (synchronous spin-wait, short durations only) |
+| `timer_start` | label | Timer |
+| `timer_lap` | timer label | Timer (record a lap time) |
+| `timer_elapsed` | timer | number (ms since start) |
+| `timer_stop` | timer | {label, total_ms, laps} |
+| `log_create` | name level | Logger  (level = minimum level to record) |
+| `log_entry` | logger level msg data? | Logger |
+| `log_info` | logger msg | Logger |
+| `log_warn` | logger msg | Logger |
+| `log_error` | logger msg | Logger |
+| `log_debug` | logger msg | Logger |
+| `log_filter` | logger level | [LogEntry]  (entries at or above level) |
+| `log_count` | logger level | number |
+| `log_last` | logger n | [LogEntry] |
+| `log_dump` | logger | void  (print all entries to stdout) |
+| `metrics_create` | name | Metrics |
+| `metrics_record` | metrics key value | Metrics |
+| `metrics_inc` | metrics key | Metrics  (increment counter by 1) |
+| `metrics_inc_by` | metrics key n | Metrics |
+| `metrics_count` | metrics key | number |
+| `metrics_avg` | metrics key | number |
+| `metrics_min` | metrics key | number |
+| `metrics_max` | metrics key | number |
+| `metrics_p95` | metrics key | number  (95th percentile) |
+| `metrics_summary` | metrics | {key: {count, avg, min, max}} |
+
+## workflow
+
+| Function | Params | Returns |
+|----------|--------|---------|
+| `workflow_create` | name steps | Workflow object |
+| `workflow_step` | name fn | WorkflowStep  (helper for defining steps) |
+| `workflow_run` | workflow initial_ctx | WorkflowResult |
+| `workflow_ok` | result | boolean |
+| `workflow_get` | result key | any  (get value from result context) |
+| `workflow_summary` | result | string  (human/AI readable summary) |
+| `task_create` | goal | Task |
+| `task_add_subtask` | task name | task |
+| `task_complete_subtask` | task name result | task |
+| `task_finish` | task result | task |
+| `task_progress` | task | number (0.0-1.0) |
+| `report_create` | title | Report |
+| `report_add` | report section_name data | Report |
+| `report_render` | report | string  (formatted text report) |
+

package/docs/ARCHITECTURE.md

@@ -0,0 +1,208 @@
+# FreeLang v11 — 시스템 아키텍처
+
+> **목적**: "프리랭을 딱 보면 전체 흐름이 파악되는 문서"
+
+---
+
+## 전체 흐름도
+
+### 1. 컴파일 파이프라인
+
+```
+FreeLang 소스코드 (.fl)
+    ↓ [LEXER — self/lexer.fl]
+    ↓ 24개 함수 (lex: src → tokens)
+    ↓ 
+Token 리스트
+    ↓ [PARSER — self/parser.fl]
+    ↓ 30개 함수 (parse: tokens → AST)
+    ↓
+AST Node 리스트
+    ↓ [CODEGEN — self/codegen.fl]
+    ↓ ~80개 함수 (cg: AST → JS + prelude)
+    ↓
+JavaScript 코드 (실행 가능)
+    ↓ [Node.js V8 엔진]
+    ↓
+실행 결과
+```
+
+**입출력 형태:**
+- **Token**: `{:kind :type :value :line :col}`
+  - kind: `LParen | RParen | Number | String | Symbol | Variable | Keyword`
+- **AST Node**: `{:kind :value :name :args :fields :line}`
+  - kind: `literal | variable | keyword | sexpr | block | pattern-match | await | throw`
+- **JS Output**: 런타임 prelude + 생성 코드
+
+---
+
+### 2. 자체호스팅 (Self-Hosting) 체인
+
+```
+bootstrap.js (TS 컴파일 결과, 1.3MB)
+    ↓ interpret 방식 (AST 직접 평가)
+    ↓ (bootstrap.js가 self/all.fl을 interpret)
+    ↓
+stage1.js (FL로 작성한 컴파일러, 57KB)
+    ↓ compile 방식 (FL → JS 생성)
+    ↓ (stage1.js가 self/all.fl을 compile)
+    ↓
+stage2.js (동일한 컴파일 결과)
+    ↓
+stage3.js ... stage10.js
+    ↓
+✅ 고정점 달성: SHA256(`0aab7ab1...`) 완전 일치
+```
+
+**의미:** stage1.js가 자신을 다시 컴파일해도 동일한 코드 생성 → 완벽한 자체호스팅 달성
+
+---
+
+### 3. 실행 경로 (3가지)
+
+#### 경로 A: Compile + Execute (가장 최신)
+
+```bash
+node --stack-size=8000 stage1.js input.fl output.js  # compile
+node output.js                                         # execute
+```
+
+- **도구**: stage1.js (canonical 컴파일러)
+- **장점**: 빠름 (V8 JIT), 코드 검사 가능
+- **사용처**: production, benchmark, CI/CD
+
+#### 경로 B: Interpret (개발 중심)
+
+```bash
+node bootstrap.js run input.fl  # interpret + execute
+```
+
+- **도구**: bootstrap.js (TS 구현 interpreter)
+- **장점**: 즉시 결과, 디버깅 용이
+- **사용처**: REPL, 개발 서버, 테스트
+
+#### 경로 C: Web Server (유일한 특수 경로)
+
+```bash
+node bootstrap.js serve app/ --port 3000
+```
+
+- **도구**: bootstrap.js (HTTP 서버 기능 포함)
+- **장점**: Full-stack (라우팅, SSR, 404 처리)
+- **사용처**: 웹 애플리케이션 개발
+- **제약**: interpreter 의존 (stage1로는 불가)
+
+---
+
+## 핵심 파일 트리
+
+```
+freelang-v11/
+├── self/                          # 자체 호스팅 코어
+│   ├── lexer.fl         (188줄)   # 토큰화 (lex: src → tokens)
+│   ├── parser.fl        (231줄)   # 파싱 (parse: tokens → AST)
+│   ├── codegen.fl       (909줄)   # 코드 생성 (cg: AST → JS)
+│   ├── all.fl           (1816줄)  # 통합 파일 (자가 컴파일 입력)
+│   ├── main.fl          (~50줄)   # 드라이버 (CLI 진입점)
+│   ├── stdlib/          (54개 파일, 629개 함수)
+│   │   ├── string.fl, list-extra.fl, math.fl, http.fl, ai.fl, ...
+│   │   └── mongodb.fl (BSON/Wire 프로토콜)
+│   └── runtime/         (3개 파일)
+│       ├── repl.js      (5.4KB)   # REPL (bootstrap 미사용)
+│       ├── http-server.js (23KB)  # HTTP 서버 (interpreter 의존)
+│       └── interpreter.js (1.1MB) # 인터프리터 번들
+├── src/                           # TypeScript 원본
+│   ├── cli.ts                     # CLI 명령어 (cmdInstall, cmdPublish)
+│   ├── eval-special-forms.ts      # (use) 탐색 경로 구현
+│   ├── stdlib-*.ts                # stdlib 정의 (자동 → bootstrap.js 번들)
+│   └── interpreter.ts             # interpreter 구현
+├── bin/
+│   └── freelang                   # CLI 진입점 (Node.js)
+├── bootstrap.js         (1.3MB)   # 부트스트랩 (1회성, stage1 생성 전용)
+├── stage1.js            (57KB)    # Canonical 컴파일러
+├── Makefile                       # 주요 명령어 (make verify-all, make compile-self)
+├── docs/
+│   ├── ARCHITECTURE.md            # 이 파일
+│   ├── AI_SYSTEM_PROMPT.md        # AI 학습 (396개 함수 시그니처)
+│   ├── AI_QUICKSTART.md           # AI 5분 가이드
+│   ├── PLUGIN_GUIDE.md            # 플러그인 작성법
+│   └── ...
+├── scripts/
+│   ├── verify-all.sh              # 통합 검증 (4개 항목)
+│   ├── verify-fixed-point-deep.sh # 고정점 검증 (stage1~10)
+│   ├── verify-self-host.sh        # tier2 PASS≥91
+│   ├── gen-ai-prompt.js           # AI 프롬프트 생성
+│   └── property-test.js           # Property-based testing (200 invariant)
+└── tests/                         # 테스트 스위트
+    ├── *.test.ts                  # Jest 테스트 (751 PASS)
+    └── l2-proof/                  # L2 증명 (12/12 PASS)
+```
+
+---
+
+## 플러그인 시스템 (Y5)
+
+### (use NAME) 탐색 순서
+
+```
+(use auth)
+    ↓ 우선순위 탐색
+    ├─ ./plugins/auth.fl         (로컬 프로젝트)
+    ├─ ~/.fl/plugins/auth.fl     (글로벌 설치)
+    ├─ ./self/stdlib/auth.fl     (내장 stdlib)
+    ├─ ./auth.fl                 (현재 디렉토리)
+    └─ ./auth                    (확장자 없음)
+    ↓ 첫 매치 → 로드 + 컴파일
+```
+
+### 플러그인 라이프사이클
+
+```
+1. freelang new weather --plugin
+   → plugins/weather.fl (메타 블록 포함)
+
+2. (편집)
+   ;; plugin: weather
+   ;; version: 1.0.0
+   [FUNC weather/forecast ...]
+
+3. freelang install weather
+   → ~/.fl/plugins/weather.fl (복사)
+
+4. make gen-ai-prompt
+   → AI_SYSTEM_PROMPT.md (함수 목록 추가)
+
+5. freelang publish plugins/weather.fl
+   → gogs.dclub.kr/kim/fl-plugins (등록)
+
+6. 다음 AI: (use weather) → weather/forecast 즉시 사용
+```
+
+---
+
+## 성능 특성
+
+| 항목 | 수치 |
+|------|------|
+| 컴파일 속도 | ~100ms (hello.fl → JS) |
+| 자가 컴파일 | ~2초 (self/all.fl → stage1-new.js) |
+| 고정점 검증 | ~5초 × 10 = 50초 |
+| 전체 verify-all | ~3.8분 (4개 검증 통합) |
+| Property test | ~30초 (200 invariant × 10 case) |
+| 번들 크기 | bootstrap.js 1.3MB, stage1.js 57KB |
+| AI학습 토큰 | AI_SYSTEM_PROMPT.md 6K tokens |
+
+---
+
+## 상태 (2026-04-26)
+
+✅ **완료**:
+- Phase A~E (언어 품질 95점)
+- Y1~Y5 (자체호스팅, 플러그인, AI 지원)
+- Phase 4 (기술 부채 0개)
+
+⚠️ **제약**:
+- bootstrap.js: 영구 의존 (HTTP 서버 기능)
+- Stage1: codegen 전용 (interpreter 없음)
+
+🎯 **등급**: **A+ (95/100)** — Production ready