Make katalyst inspect . tell a coherent story about the current directory

[abegong]

Context

The first command many users are likely to run is:

katalyst inspect .

For a raw directory, this runs the three raw-source inspectors: file_tree, file_tree_content, and document_shape.

The current default output is not serving either human or AI audiences well. It exposes a generic classes / outliers structure, but the content does not tell a coherent story and does not feel grounded in what is actually in the directory.

The default output should feel like Katalyst has understood how the directory works.

Product goal

Make katalyst inspect . produce a readable, grounded first-pass understanding of the current directory: its tree, content regions, document conventions, likely groups, and exceptions.

This should remain descriptive. Inspectors report observed evidence; they should not recommend a schema or mutate the project.

Questions the output should answer at a glance

• What kind of thing does this directory appear to be?
• What are the major regions of the directory?
• For very small directories, what is the actual tree structure?
• Where are the markdown/content files?
• Which directories parse cleanly, have frontmatter, or share key sets?
• Which files appear to belong together as candidate collections?
• What conventions did Katalyst infer: naming, extensions, frontmatter, body sections?
• Which files or directories are exceptions, and what makes them different?
• How much evidence is there, and where should the reader be cautious because the input is tiny?
• What concrete paths support each claim?

Child issues

Focused implementation issues:

• Improve raw-source inspector: file_tree should explain the directory layout #110
• Improve raw-source inspector: file_tree_content should explain directory content shape #111
• Improve raw-source inspector: document_shape should tell a coherent candidate-collection story #112

Acceptance criteria

• The default Markdown report from katalyst inspect . reads as a coherent directory understanding, not a dump of summarizer internals.
• The report is useful to a human scanning a terminal and to an AI agent trying to ground follow-up reasoning.
• Very short directories show their structure directly.
• Larger directories summarize without hiding the concrete paths that support the summary.
• The generic classes / outliers vocabulary is replaced or supplemented in human output with domain-specific language.
• JSON output remains machine-readable and complete.
• Snapshot coverage locks the improved first-run experience.

[abegong]

Closed by #114, with the product direction updated during review. katalyst inspect . now tells the raw directory story through file_tree and file_content_shape, avoids generic classes / outliers in the default human report, keeps JSON complete, and has snapshot coverage for the first-run experience. Candidate-collection grouping was intentionally dropped with document_shape.