feat: folder-based type inference + docs command

[mindsocket]

Summary

• Implements automatic node type inference from folder structure in the markdown plugin (closes Support content type inference from folder structure #73, Allow for parsing hints in space config #44)
• Replaces readme command with docs [topic] command; ships docs/ files with the package

Type inference (#73, #44)

Adds typeInference config under plugins.markdown:

• mode: "folder-name" (default) — matches the leaf directory name case-insensitively against schema type names and typeAliases keys. Files at the space root are never inferred.
• folderMap — explicit path → type mapping (longest-prefix match, trailing slashes normalised, values may be aliases). Unresolvable values throw a hard error at parse time.
• Explicit type: in frontmatter always wins over inferred type.
• extractEntityInfo moved from command layer to src/schema/schema.ts (cleaner API); extractSchemaTypeNames added as a thin wrapper returning Set<string>.

Docs command

• ost-tools docs → README (replaces ost-tools readme)
• ost-tools docs config → plugin config reference
• ost-tools docs concepts / schema / rules → respective doc files
• docs/config.md created with the full plugin config reference (extracted from README)
• Four user-facing doc files added to package.json files so they ship with the package
• README plugin config block trimmed to a one-liner pointer
• SKILL.md updated: static plugin config list replaced with ost-tools docs config pointer

Test plan

• bun run test — 391 tests pass
• bun run typecheck — clean
• ost-tools docs renders README
• ost-tools docs config renders config reference
• ost-tools docs unknown exits 1 with available topics listed
• ost-tools validate <space> with typeInference: { mode: "folder-name" } in config infers type from leaf directory

[claude]

Claude finished @mindsocket's task in 3m 30s —— View job

---

Code Review

I've completed reviewing this PR. Here's my analysis:

---

Summary

This PR implements two major features:

1. Folder-based type inference for the markdown plugin (closes Support content type inference from folder structure #73, Allow for parsing hints in space config #44)
2. docs command replacing readme with shipped documentation

Overall Assessment: ✅ LGTM with minor suggestions

The implementation is well-designed, thoroughly tested, and properly documented. The code follows the project's established patterns and conventions.

---

Type Inference Implementation

Strengths

Clean API design (src/plugins/markdown/util.ts):

• inferTypeFromPath has clear, single-purpose logic
• Proper separation between mode: 'off', folder-name, and folderMap strategies
• Case-insensitive matching is a nice UX touch

Good integration (src/plugins/markdown/read-space.ts):

• Type inference only runs when needed (line 68-69: guards with mode !== 'off')
• Explicit type: in frontmatter correctly takes precedence (line 93-95)
• Clean integration with existing applyFieldMap and coerceDates flow

Schema refactor (src/schema/schema.ts):

• Moving extractEntityInfo from commands to schema layer is the right call
• extractSchemaTypeNames is a clean, focused wrapper (lines 468-473)
• Proper reuse of existing schema inspection logic

Comprehensive tests (tests/plugins/markdown/read-space-directory-type-inference.test.ts):

• 229 lines covering all scenarios and edge cases
• Tests for: case-insensitivity, alias resolution, folderMap longest-prefix, trailing slash normalization, explicit type override, root files, and error cases
• Excellent coverage of the plan's requirements

Documentation

New docs/config.md is thorough:

• Clear explanation of both modes
• Good examples for folderMap usage
• Proper warning about longest-prefix matching behavior
• Security notice preserved

docs/concepts.md updated:

• Clear "Type inference" section under Space directory
• Explains both modes concisely

---

Docs Command Implementation

Clean design (src/commands/docs.ts):

• Simple topic lookup with helpful error for unknown topics
• Terminal rendering with ANSI formatting for readability
• Proper integration with src/index.ts (line 158-160)

Good packaging (package.json):

• Four doc files added to files array (lines 14-17)
• Will ship with the npm package

Documentation updates:

• README.md: Plugin config section trimmed to one-liner pointing to ost-tools docs config
• SKILL.md: Updated to reference new docs command

---

Hook Feedback: Linting Warning

The pre-stop hook detected a linting warning from biome:

.claude-pr/CLAUDE.md internalError/fs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ! Deeply nested symlink expansion.

Fix: I've committed a change to add .claude-pr/ to .gitignore. This directory is created by the GitHub Action for PR reviews and contains symlinks that cause biome to warn. It's not part of the project source code.

.miro-cache/
config.json
.claude/settings.local.json
.claude/worktrees/
+ .claude-pr/
CLAUDE.local.md

Note: I cannot push this fix due to GitHub Actions permissions. You'll need to manually add .claude-pr/ to .gitignore or cherry-pick commit dd0c801.

---

Test Results

• ✅ 391 tests pass (0 failures, 741 assertions)
• ⚠️ Linting: 1 warning (addressed by .gitignore fix above)
• Test coverage is comprehensive for type inference

---

Minor Suggestions for Future Enhancements

1. Performance consideration: For very large spaces, computing knownTypes once before the file loop (line 68-69) is good. Consider caching this result if the schema is reused across multiple parses.

2. Error messages: The error for unresolvable folderMap values (line 34-36 in util.ts) is helpful. Consider including the list of valid types in the error message for even better UX.

3. Documentation: Consider adding a note in docs/config.md about the interaction between typeInference and fieldMap - e.g., if someone uses fieldMap to rename type to something else, type inference won't work (since it explicitly looks for data.type).

---

Test Plan Status

Based on my review:

• bun run test — 391 tests pass ✓
• bun run typecheck — requires approval to run (but implementation looks type-safe)
• ost-tools docs renders README (code review confirms)
• ost-tools docs config renders config reference (file exists and is complete)
• ost-tools docs unknown exits 1 with available topics listed (lines 17-20 in docs.ts)
• Type inference with mode: "folder-name" works (comprehensive test coverage)

---

Conclusion

This is a well-executed PR that addresses the requirements in issues #73, #44, and #78. The implementation is clean, well-tested, and properly documented. The type inference feature provides a nice quality-of-life improvement for users organizing their markdown files by type, and the docs command is a thoughtful replacement for the readme command.

Recommendation: ✅ Approve (with .gitignore fix applied)

[claude]

Claude finished @mindsocket's task in 1m 34s —— View job

---

Code Review

Reviewing PR #84: feat: folder-based type inference + docs command

Tasks:

• Analyze PR context and understand requirements
• Review type inference implementation
• Review docs command implementation
• Check test coverage and quality
• Verify documentation updates
• Provide comprehensive review feedback

---

Summary

This PR implements two major features:

1. Folder-based type inference for the markdown plugin (closes Support content type inference from folder structure #73, Allow for parsing hints in space config #44)
2. docs command replacing readme with shipped documentation

Overall Assessment: ✅ LGTM with minor suggestions

The implementation is well-designed, thoroughly tested, and properly documented. The code follows the project's established patterns and conventions.

---

Type Inference Implementation

Strengths

Clean API design (src/plugins/markdown/util.ts):

• inferTypeFromPath has clear, single-purpose logic
• Proper separation between mode: 'off', folder-name, and folderMap strategies
• Case-insensitive matching is a nice UX touch (util.ts:39-49)
• Longest-prefix matching for folderMap is well-implemented (util.ts:21-26)

Good integration (src/plugins/markdown/read-space.ts):

• Type inference only runs when needed (lines 68-69: guards with mode !== 'off')
• Explicit type: in frontmatter correctly takes precedence (lines 93-95)
• Clean integration with existing applyFieldMap and coerceDates flow

Schema refactor (src/schema/schema.ts):

• Moving extractEntityInfo from commands to schema layer is the right call
• extractSchemaTypeNames is a clean, focused wrapper (lines 468-473)
• Proper reuse of existing schema inspection logic

Comprehensive tests (tests/plugins/markdown/read-space-directory-type-inference.test.ts):

• 229 lines covering all scenarios and edge cases
• Tests for: case-insensitivity, alias resolution, folderMap longest-prefix, trailing slash normalization, explicit type override, root files, and error cases
• Excellent coverage of the requirements

Documentation

New docs/config.md is thorough:

• Clear explanation of both modes
• Good examples for folderMap usage
• Proper warning about longest-prefix matching behavior
• Security notice preserved

docs/concepts.md updated:

• Clear "Type inference" section under Space directory
• Explains both modes concisely

---

Docs Command Implementation

Clean design (src/commands/docs.ts):

• Simple topic lookup with helpful error for unknown topics (lines 17-20)
• Terminal rendering with ANSI formatting for readability
• Proper integration with src/index.ts

Good packaging (package.json):

• Four doc files added to files array (lines 14-17)
• Will ship with the npm package

Documentation updates:

• README.md: Plugin config section trimmed to one-liner pointing to ost-tools docs config (line 49)
• SKILL.md: Updated to reference new docs command (lines 38-39, 113-117)

---

Test Results

• ✅ 391 tests pass (0 failures, 741 assertions)
• ✅ TypeScript type checking passes (no errors)
• Test coverage is comprehensive for type inference

---

Minor Suggestions for Future Enhancements

1. Performance consideration: For very large spaces, computing knownTypes once before the file loop (read-space.ts:68-69) is good. Consider caching this result if the schema is reused across multiple parses.

2. Error messages: The error for unresolvable folderMap values (util.ts:34-36) is helpful. Consider including the list of valid types in the error message for even better UX.

3. Documentation: Consider adding a note in docs/config.md about the interaction between typeInference and fieldMap - e.g., if someone uses fieldMap to rename type to something else, type inference won't work (since it explicitly looks for data.type).

---

Test Plan Status

Based on my review:

• bun run test — 391 tests pass ✓
• bun run typecheck — clean ✓
• ost-tools docs renders README (code review confirms)
• ost-tools docs config renders config reference (file exists and is complete)
• ost-tools docs unknown exits 1 with available topics listed (docs.ts:17-20)
• Type inference with mode: "folder-name" works (comprehensive test coverage)

---

Conclusion

This is a well-executed PR that addresses the requirements in issues #73, #44, and #78. The implementation is clean, well-tested, and properly documented. The type inference feature provides a nice quality-of-life improvement for users organizing their markdown files by type, and the docs command is a thoughtful replacement for the readme command.

Recommendation: ✅ Approve