docs: documentation overhaul (ExDoc structure, 7 new guides, example fixes)#63
Merged
Conversation
… fixes
Comprehensive documentation review/reorganization after months of feature growth.
ExDoc structure (mix.exs):
- Eliminate 67 orphaned modules — every documented module now grouped.
- New module groups: Multi-Agent (Teams), Decision Graph, Messages & Streaming,
HTTP Backends, Structured Output, Utility Tools, Mix Tasks.
- Complete the Providers group (+Gemini/Mistral/Custom/VLLM/SGLang) and expand
the Evaluation subtree (optimizer/evaluators/reporters).
- Wire previously-unlisted guides into extras; add AGENTS.md, CONTRIBUTING.md,
guides index, and the HTTP benchmark as extras; group changelog.
- 0 broken-link warnings (was failing to resolve AGENTS/CONTRIBUTING/examples/etc).
New subsystem guides (docs/guides/):
- teams, decisions, research, fallback, permissions, observability, providers.
All grounded in source. Observability guide confirms telemetry uses the
[:nous, :provider, ...] namespace (resolves prior-review C-9).
README / getting-started / indexes:
- Add Teams/Decisions/Permissions/Fallback/Observability to the feature index.
- Fix the broken AgentDynamicSupervisor.start_agent persistence snippet.
- Regenerate the two stale doc indexes (listed 6/8 of 23 guides) into one
categorized index; fix broken ../doc/ links; normalize example links to
relative; fix contradictory projects/README; bump version refs to 0.16.1.
Examples:
- Fix broken examples: telemetry (top-level defp), 08_tool_testing (called?/1 →
call_count/1), eval yaml suite (tags → all_tags), error_handling
(MaxIterationsReached → MaxIterationsExceeded), cancellation (cancel →
cancel_execution), anthropic (safe result[:thinking]), vllm/sglang (base_url).
- Fix `deps:` silent no-op: deps is a run-time option, moved from Nous.new/2 to
the run call in 13_sub_agents and memory/auto_update.
- New examples: advanced/{teams,decisions,deep_research,fallback}.exs.
- Index orphaned examples (eval/*, custom_providers, vertex_ai_multi_region).
Housekeeping:
- Delete duplicate docs/llm_council_design.md (identical to docs/design/ copy).
- Fix duplicate CHANGELOG [0.13.0] header (Hooks release renumbered 0.12.14);
add Keep-a-Changelog preamble + version compare-links.
Verified: mix format, compile --warnings-as-errors, docs (0 link warnings),
credo --strict (clean); offline examples run green.
Parallel specialist review (examples / guides / ExDoc config) found: - BLOCKER: examples/advanced/fallback.exs used `result.fallback_used`, which is not a key on the run-result map (it only exists as telemetry metadata) and would raise KeyError on the success path. Now reports failover via the documented `result.deps[:active_model]` instead. - MINOR: teams.md said SharedState `terminate/1`; the callback is `terminate/2`. - MINOR: permissions.md implied `:approval_handler` is an Agent option; it's a field on the run context (Nous.Agent.Context). mix.exs ExDoc config, all 7 new guides, all 13 reviewed examples, and every index link otherwise verified clean (no phantom modules, no @moduledoc-false leaks, all extras + links resolve).
nyo16
force-pushed
the
docs/overhaul-v0.16
branch
from
e6a0f7d to
bee5889
Compare
nyo16
changed the title
nyo16
added a commit
that referenced
this pull request
Jun 22, 2026
The audit content for releases 0.16.2-0.16.5 had piled up under [Unreleased] and was never versioned (releases were tagged without splitting the changelog). Split it into dated sections using the tag-snapshot delta as ground truth (the [Unreleased] content at each tag = that release's cumulative content): - [0.16.2] 2026-05-16 — provider marshalling, ETS lifecycle, OTP hygiene, telemetry (#58) - [0.16.3] 2026-05-29 — security pass: RCE gate, SSRF, sandbox + audit findings (#59) - [0.16.4] 2026-06-05 — security/OTP/test hardening (#60); summarized from the commit, since this release added nothing to the changelog at the time - [0.16.5] 2026-06-12 — InputGuard fail-closed, permissive execute gate, policy bypass (#61) - [Unreleased] (-> 0.16.6) — perf hot-path hardening (#62) + the docs overhaul (#63) Bullets were moved verbatim, not rewritten; dates match the git tags exactly. Added compare-links for each new version. Verified: no [Unreleased] bullet was dropped, mix docs is 0 warnings, mix format clean.
nyo16
added a commit
that referenced
this pull request
Jun 22, 2026
Post-overhaul cleanup (follow-up to #63). CHANGELOG: - Add the missing 0.12.13 (custom: provider, #34) and 0.12.12 (memory/context/ AgentServer fixes) entries — both had release tags but no changelog sections — with matching compare-links. mix docs — now 0 warnings: - Qualify `Agent.new/2` -> `Nous.Agent.new/2` (resolves & links) in CHANGELOG. - De-link historical references to since-private/hidden APIs in CHANGELOG and AGENTS.md (run_with_tools/6, Gemini.parse_content/1, Model.default_receive_timeout/1, Provider.request/3, Plugins.Memory.init/2, Nous.Application, Persistence.ETS.TableOwner). New examples (all run or degrade gracefully without a provider): - examples/llm_oneshot.exs — bare Nous.LLM API (generate_text/3, /3 bang, stream_text/3). - examples/knowledge_base.exs — KB store add/search + KB agent plugin. - examples/advanced/summarization.exs — auto-compaction via the Summarization plugin. - examples/advanced/web_tools.exs — WebFetch/SearchScrape/Tavily/Brave tools. - Indexed all four in examples/README.md. Docs: - Clarify the three LiveView examples' distinct roles (patterns reference vs complete chat app vs multi-agent dashboard). Verified: mix format, compile --warnings-as-errors, docs (0 warnings), credo --strict (clean); new examples run green offline. Note: v0.16.2-v0.16.5 are tagged but lack CHANGELOG entries and mix.exs @Version (0.16.1) is behind the latest tag — deferred to a separate version/release reconciliation pass rather than guessing release notes.
nyo16
added a commit
that referenced
this pull request
Jun 22, 2026
The audit content for releases 0.16.2-0.16.5 had piled up under [Unreleased] and was never versioned (releases were tagged without splitting the changelog). Split it into dated sections using the tag-snapshot delta as ground truth (the [Unreleased] content at each tag = that release's cumulative content): - [0.16.2] 2026-05-16 — provider marshalling, ETS lifecycle, OTP hygiene, telemetry (#58) - [0.16.3] 2026-05-29 — security pass: RCE gate, SSRF, sandbox + audit findings (#59) - [0.16.4] 2026-06-05 — security/OTP/test hardening (#60); summarized from the commit, since this release added nothing to the changelog at the time - [0.16.5] 2026-06-12 — InputGuard fail-closed, permissive execute gate, policy bypass (#61) - [Unreleased] (-> 0.16.6) — perf hot-path hardening (#62) + the docs overhaul (#63) Bullets were moved verbatim, not rewritten; dates match the git tags exactly. Added compare-links for each new version. Verified: no [Unreleased] bullet was dropped, mix docs is 0 warnings, mix format clean.
nyo16
added a commit
that referenced
this pull request
Jun 22, 2026
…#64) * docs: follow-ups — CHANGELOG entries, silent mix docs, 4 new examples Post-overhaul cleanup (follow-up to #63). CHANGELOG: - Add the missing 0.12.13 (custom: provider, #34) and 0.12.12 (memory/context/ AgentServer fixes) entries — both had release tags but no changelog sections — with matching compare-links. mix docs — now 0 warnings: - Qualify `Agent.new/2` -> `Nous.Agent.new/2` (resolves & links) in CHANGELOG. - De-link historical references to since-private/hidden APIs in CHANGELOG and AGENTS.md (run_with_tools/6, Gemini.parse_content/1, Model.default_receive_timeout/1, Provider.request/3, Plugins.Memory.init/2, Nous.Application, Persistence.ETS.TableOwner). New examples (all run or degrade gracefully without a provider): - examples/llm_oneshot.exs — bare Nous.LLM API (generate_text/3, /3 bang, stream_text/3). - examples/knowledge_base.exs — KB store add/search + KB agent plugin. - examples/advanced/summarization.exs — auto-compaction via the Summarization plugin. - examples/advanced/web_tools.exs — WebFetch/SearchScrape/Tavily/Brave tools. - Indexed all four in examples/README.md. Docs: - Clarify the three LiveView examples' distinct roles (patterns reference vs complete chat app vs multi-agent dashboard). Verified: mix format, compile --warnings-as-errors, docs (0 warnings), credo --strict (clean); new examples run green offline. Note: v0.16.2-v0.16.5 are tagged but lack CHANGELOG entries and mix.exs @Version (0.16.1) is behind the latest tag — deferred to a separate version/release reconciliation pass rather than guessing release notes. * chore: bump @Version to 0.16.6 mix.exs @Version had been left at 0.16.1 across the v0.16.2-v0.16.5 release tags (each tagged without bumping it). master is 3 commits past v0.16.5, so the next release is 0.16.6. Note: the matching CHANGELOG entries for 0.16.2-0.16.5 are still outstanding (separate version/release reconciliation). * docs(CHANGELOG): split accumulated [Unreleased] into 0.16.2-0.16.5 The audit content for releases 0.16.2-0.16.5 had piled up under [Unreleased] and was never versioned (releases were tagged without splitting the changelog). Split it into dated sections using the tag-snapshot delta as ground truth (the [Unreleased] content at each tag = that release's cumulative content): - [0.16.2] 2026-05-16 — provider marshalling, ETS lifecycle, OTP hygiene, telemetry (#58) - [0.16.3] 2026-05-29 — security pass: RCE gate, SSRF, sandbox + audit findings (#59) - [0.16.4] 2026-06-05 — security/OTP/test hardening (#60); summarized from the commit, since this release added nothing to the changelog at the time - [0.16.5] 2026-06-12 — InputGuard fail-closed, permissive execute gate, policy bypass (#61) - [Unreleased] (-> 0.16.6) — perf hot-path hardening (#62) + the docs overhaul (#63) Bullets were moved verbatim, not rewritten; dates match the git tags exactly. Added compare-links for each new version. Verified: no [Unreleased] bullet was dropped, mix docs is 0 warnings, mix format clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Comprehensive documentation review and reorganization after several months of feature growth. No library code behavior changes — docs, examples, and ExDoc config only.
ExDoc / HexDocs structure (
mix.exs)extras; addAGENTS.md,CONTRIBUTING.md, a guides index, and the HTTP benchmark as extras; group the changelog.AGENTS.md,CONTRIBUTING.md,examples/, etc.).New subsystem guides (
docs/guides/)teams,decisions,research,fallback,permissions,observability,providers— all grounded in source. The observability guide confirms telemetry uses the[:nous, :provider, ...]namespace (resolves prior-review C-9).README / getting-started / indexes
AgentDynamicSupervisor.start_agentpersistence snippet.../doc/links; normalize example links to relative; fix the contradictoryprojects/README; bump version refs to 0.16.1.Examples
telemetry(top-leveldefp),08_tool_testing(called?/1→call_count/1),eval/02_yaml_suite(tags→all_tags),error_handling(MaxIterationsReached→MaxIterationsExceeded),cancellation(cancel→cancel_execution),anthropic(saferesult[:thinking]),vllm/sglang(base_url).deps:silent no-op:depsis a run-time option, moved fromNous.new/2to the run call in13_sub_agentsandmemory/auto_update.advanced/{teams,decisions,deep_research,fallback}.exs.eval/*,custom_providers,vertex_ai_multi_region).Housekeeping
docs/llm_council_design.md(identical to thedocs/design/copy).[0.13.0]header (the Hooks release renumbered to0.12.14); add a Keep-a-Changelog preamble + version compare-links.Verification
mix format,mix compile --warnings-as-errors,mix docs(0 link warnings),mix credo --strict(clean); offline examples run green. A 3-track parallel review (examples / guides / ExDoc config) found 1 blocker + 2 minor prose issues, all fixed and re-verified.