docs: restructure into Diátaxis layout#24
Conversation
…uides/reference)
Reorganize the flat docs/ tree into the four-section Diátaxis split so the
on-ramp is clearer and reference material is easier to find.
- Move existing reference docs into docs/reference/ (cli-contract→cli,
skill-prompts→plugin, repo-bootstrap, releasing).
- Split docs/overview.md into explanation/{what-is-clast,architecture,
data-model,conventions}.md.
- Extract entry-frontmatter and config into their own reference pages.
- Add getting-started/ (install, first-snapshot, install-the-plugin) and
guides/ (automate-with-cron/-systemd, curate-an-entry, use-breadcrumbs,
morning-briefing, repair-the-journal, query-recipes).
- Add docs/README.md as the index.
- Update README.md and source-comment doc references to the new paths.
- Promote examples/workflows/morning-briefing.md to guides/.
docs/steps/* and docs/build-steps.md are left untouched — they are
historical build artifacts that intentionally reference the
pre-restructure paths.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
clast/docs/guides/morning-briefing.md
Line 1 in 50e1aa9
Restore the packaged workflow example
Moving this walkthrough out of examples/ breaks the npm release guard: package.json runs ./contrib/npm-pack-check.sh in prepublishOnly, and that script still requires examples/workflows/morning-briefing.md. With this commit, npm pack --dry-run no longer includes that path, so the check exits with MISSING from tarball: examples/workflows/morning-briefing.md and npm publishes are blocked until the packaged path or the check is updated.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
contrib/npm-pack-check.sh requires examples/workflows/morning-briefing.md in the published tarball (and docs/ is in its forbidden list, so the file can't live only under docs/guides/). Restore the file to its packaged location and link to it from the guides index and README instead of duplicating it. Reported by Codex on #24.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 70558bdbc5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## 3. Inspect a single session | ||
|
|
||
| ```sh | ||
| clast sessions --since -7d --json | jq -r '.[0].uuid' # grab a uuid |
There was a problem hiding this comment.
In this walkthrough, clast sessions --json does not emit a uuid key; the sessions command builds rows with session_id instead. Following this command returns null, so the next clast show <session-uuid>/entries write --session <uuid> steps fail for users copying the guide. Use .[0].session_id here.
Useful? React with 👍 / 👎.
|
|
||
| ```sh | ||
| # Just the curated ratio for the last week | ||
| clast stats --since -7d --json | jq '.curated_sessions / .total_sessions' |
There was a problem hiding this comment.
The stats subcommand emits curated and sessions keys, not curated_sessions or total_sessions, so this recipe evaluates missing fields and fails instead of producing the curated ratio. Users following the query guide need this to divide .curated / .sessions (with any desired zero guard).
Useful? React with 👍 / 👎.
1 participant
Summary
Reorganize the flat
docs/tree into four Diátaxis sections (explanation/,getting-started/,guides/,reference/) so the on-ramp is clearer and reference material is easier to find. Modeled loosely on xcind's docs layout.What moved
docs/cli-contract.md→docs/reference/cli.mddocs/skill-prompts.md→docs/reference/plugin.mddocs/repo-bootstrap.md→docs/reference/repo-bootstrap.mddocs/releasing.md→docs/reference/releasing.mdexamples/workflows/morning-briefing.md→docs/guides/morning-briefing.mddocs/overview.mdsplit intoexplanation/{what-is-clast,architecture,data-model,conventions}.mdand deletedWhat's new
docs/README.md— section indexdocs/explanation/— what-is-clast, architecture, data-model, conventionsdocs/getting-started/— install, first-snapshot, install-the-plugindocs/guides/— automate-with-cron, automate-with-systemd, curate-an-entry, use-breadcrumbs, repair-the-journal, query-recipes (+ promoted morning-briefing)docs/reference/— entry-frontmatter and config extracted as standalone pagesLink rewrites
README.md"Documentation" section now points at the new layout.lib/clast/**.bashandtest/test-registry.shupdated to the new paths/anchors.docs/steps/*anddocs/build-steps.mdare intentionally left untouched — perAGENTS.md("planning docs are stable references that later steps point at"), the step files are historical build artifacts and accurately reference the pre-restructure paths.Test plan
make lintpassesmake testpasses (exit 0)docs/steps/anddocs/build-steps.md(docs/README.mdmentions the old paths only in the historical-note section)docs/README.mdand walk the linked sections to confirm the on-ramp reads cleanly