⏺ CONTRIBUTING.md is clean — no issues. It covers process only (shell…

[navicore]

… commands, PR workflow, code style), contains no Seq code examples, and nothing that

could be stale.

That completes the full documentation review. Here's a summary of all 16 tasks:

┌─────┬─────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────┐
│ # │ File │ Changes │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 1 │ README.md │ Fixed seqc commands, removed stale limitations, spawn API │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 2 │ language-guide.md │ Many word name fixes, removed future-work sections │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 3 │ TYPE_SYSTEM_GUIDE.md │ Bool/Int corrections, removed pre-impl sections │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 4 │ TCO_GUIDE.md │ Fixed operator names, musttail accuracy │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 5 │ STDLIB_REFERENCE.md │ Signatures, word names, removed placeholders │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 6 │ BATTERIES_INCLUDED.md │ Major rewrite — removed all pre-implementation content │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 7 │ FFI_GUIDE.md │ string.length, i.>, removed future-work │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 8 │ GRAMMAR.md │ Added Yield effect annotation, fixed i.divide example, naming conventions │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 9 │ GLOSSARY.md │ CSP example (chan.make), fixed cond syntax entirely │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 10 │ INCLUDE_SYSTEM.md │ Removed to-do list, fixed stdlib lookup description, io.write-line │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 11 │ OBSERVABILITY_GUIDE.md │ SEQ_REPORT=words, removed internal C symbols │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 12 │ TESTING_GUIDE.md │ i.+, drop after i./ calls │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 13 │ ARCHITECTURE.md │ Variant API, JSON tags, factorial, concurrency API, TCO link, removed false limitation │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 14 │ EXAMPLES.md │ i.mod, removed dev-notes section, string escapes, YAML API names, concurrency API, seqc build │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 15 │ MIGRATION_4.0.md + MIGRATION_3.0.md │ No changes needed │
├─────┼─────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────┤
│ 16 │ CONTRIBUTING.md │ No changes needed │
└─────┴─────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────┘

[claude]

Documentation Review

This is a solid documentation sweep that brings the docs in line with the 4.0 API. The changes are consistently in the right direction: removing stale roadmap content, correcting operator/word names, and fixing type signatures throughout. A few things worth addressing before merge:

---

Issues

1. Incomplete symbol-notation migration in ARCHITECTURE.md (JSON tags section)

Tags 0-2 are updated to use :Symbol notation but tags 3-5 still use the old numeric format:

• Tag :JsonNull (0 fields) — updated
• Tag :JsonBool (1 field: Bool) — updated
• Tag :JsonNumber (1 field: Float) — updated
• Tag 3: JsonString (1 field: String) — still old style
• Tag 4: JsonArray (N fields: elements) — still old style
• Tag 5: JsonObject (2N fields: ...) — still old style

Should be :JsonString, :JsonArray, :JsonObject for consistency.

---

2. Possible forward reference in FFI_GUIDE.md

The updated text says:

Use os.home-dir and os.path-join to build paths from the home directory rather than hardcoding /tmp paths.

If os.home-dir and os.path-join are not yet implemented, this introduces exactly the kind of forward reference the PR is trying to eliminate. Worth verifying these exist in the stdlib before landing.

---

3. Minor: cond stack effect in STDLIB_REFERENCE.md

The new signature ( T [T--T Bool] [T--T] ... N -- T ) uses inline quotation notation that is not consistent with how other higher-order words are documented (e.g., list.map). A short prose description alongside a simpler signature might be clearer and more consistent.

---

Positive highlights

• // to # comment style fix throughout Seq code examples is a clean consistency improvement.
• Adding drop after i./ calls in TESTING_GUIDE.md and GRAMMAR.md is correct — the success Bool must be consumed.
• The Bool vs Int type corrections in STDLIB_REFERENCE.md, TYPE_SYSTEM_GUIDE.md, and language-guide.md correctly reflect Bool as a distinct type rather than the old Int 0/1 convention.
• Updated error message formats in TYPE_SYSTEM_GUIDE.md are much more readable ((..a String) vs the old Cons { rest: RowVar("a"), top: String }).
• Removing the (Implemented) / (Complete) status markers from section titles and table columns prevents them from going stale again.
• The TCO guide trim is well-judged — removing unimplemented design phases while keeping the conceptually important tail-position explanation is the right call.

[claude]

Documentation Review — PR #356

This is a documentation-only PR updating 14 files (275 additions, 1051 deletions) to align docs with the current state of the language and project structure. Overall this is high-quality, well-scoped work. Notes below.

---

Strengths

• Consistent API rename sweep: Old names (spawn, make-channel, send, receive, i.add, write_line, etc.) are updated to namespaced equivalents (strand.spawn, chan.make, chan.send, chan.receive, i.+, io.write-line) uniformly across all files.
• Bool type accuracy: Replacing the old 'Int 0/1 is Bool' fiction with accurate Bool type tracking throughout TYPE_SYSTEM_GUIDE.md and language-guide.md is a meaningful correctness improvement.
• Removed misleading Vision / pre-implementation content: The BATTERIES_INCLUDED.md and TCO_GUIDE.md cuts are substantial and appropriate — docs describing unimplemented features are a maintenance hazard and mislead users.
• Stack effect fixes: The swap-and-add signature corrected to ( Int Int Int -- Int Int ) is accurate (swap + add consumes two of the three inputs, leaving the third untouched), and the division examples adding drop for the quotient/remainder dual-return are correct.
• Internal cross-references fixed: docs/TCO_DESIGN.md -> docs/TCO_GUIDE.md and GLOSSARY.md -> docs/GLOSSARY.md are correct.

---

Issues / Questions

1. PR title looks AI-generated

The title '⏺ CONTRIBUTING.md is clean — no issues...' appears to be the output of an AI code review agent, not a human-authored commit message. Consider updating to something like: docs: sync all guides to current API (v4.0 naming conventions).

2. Placeholder identifier in ARCHITECTURE.md concurrency example

In the concurrency section, chan-id is used as a placeholder name but looks like a real Seq word to newcomers. Consider matching the style in language-guide.md which shows actual stack flow, or add a comment clarifying it is a placeholder.

3. chan.yield vs yield — verify the word name

ARCHITECTURE.md now documents chan.yield for cooperative yield, but this word does not appear in language-guide.md or the README. If the word is actually chan.yield, it should be consistent in the stdlib reference too. If it is still the bare yield word, this rename is incorrect.

4. STDLIB_REFERENCE.md drops primitive count without replacement

Old: 152 primitives implemented in the runtime
New: just Built-in Operations

Removing a stale count is correct, but consider adding a note like see crates/compiler/src/builtins.rs for the canonical list so users know where to look.

5. BATTERIES_INCLUDED.md table lost the FFI Effort column silently

The capability table dropped the FFI Effort column. If these capabilities are now implemented, noting them as available vs planned would help. If some are still planned, the column removal hides useful information.

---

Minor Nits

• README.md: The seqc examples/basics/hello-world.seq line has extra trailing spaces before the comment — cosmetic only.
• STDLIB_REFERENCE.md: The sentence No additional utilities beyond the built-in [Map Operations] is slightly awkward; 'No additional map utilities' reads more naturally.

---

Summary

Category	Assessment
Code quality	N/A (docs only)
Accuracy	Good — most changes improve correctness
Completeness	Good — 14 files swept consistently
Potential bug	1 word name to verify: chan.yield
Security	N/A
Test coverage	N/A

Recommend verifying the chan.yield word name and updating the PR title before merging. The rest are suggestions. Good cleanup overall.