Documentation improvements for clarity and agent support#2
Merged
david-w-t merged 10 commits intodavidwt-com:mainfrom Mar 29, 2026
Merged
Documentation improvements for clarity and agent support#2david-w-t merged 10 commits intodavidwt-com:mainfrom
david-w-t merged 10 commits intodavidwt-com:mainfrom
Conversation
Adds config/sys.config with a rotating file handler (logger_std_h) writing to log/seerstone.log and a console handler for errors. Replaces ad-hoc io:format diagnostic calls in dictionary_imp, nref_allocator, and nref_server with structured logger:info/warning/error calls. Updates rebar.config to reference the new sys_config path.
nref_include was Dallas's earlier unsupervised, plain-function predecessor to nref_server. Its logic was fully absorbed into nref_server as a proper supervised gen_server. The file was never referenced from anywhere in the compiled codebase. Deletes the file and marks TASKS.md item 4 as done.
Propagate the knowledge graph model from knowledge-graph-database-guide.md into CLAUDE.md, README.md, TASKS.md, and all apps/*/CLAUDE.md files. Expand task 3 into six sub-tasks (3a-3f) with concrete APIs and schemas. Fix stale references to nref_include.erl and incorrect compile commands. Apply corrections to knowledge-graph-database-guide.md: - Flatten relationship record structure (reciprocal is a sibling of value) - Correct instance name attribute description (not globally unique) - Broaden compositional parent label to part-of parent - Fix strata diagram arrow direction (references point upward) - Add Literal Attributes as a third attribute node type - Rename Articulation Principles to Modelling Guidelines - Reorder Instance Inheritance Process steps by priority - Expand Multiple Inheritance section with balanced pitfall guidance - Rename Class to Template in View/Document Derivation table
Apply fixes from the current session across all documentation: - Add Literal Attributes as a third attribute node type throughout - Correct inheritance priority order to 4-step explicit list in all files - Update graphdb_attr descriptions to replace 'external name attributes' - Rewrite TASKS.md Session Notes as a status table with restated pending concerns (A-E)
…aph-database-guide Rename middle column of reciprocity examples table from 'Relationship' to 'Type' (the cells contain relationship type names, not relationship labels). Replace editorial summaries in the 1997 and 1999 Sources entries with the actual patent title for all three Noyes patents — all three share the title 'Method for representation of knowledge in a computer as a network database system'; continuation-in-part lineage noted for 5,594,837 and 5,878,406. Marks TASKS.md issues D and E as applied.
Add a Current Status section noting the project compiles clean, nref and dictionary are complete, and graphdb workers are the remaining work. Replace the partial config/sys.config snippet with an accurate summary showing both the kernel/logger and seerstone_graph_db stanzas. Note that apps/seerstone/priv/default.config is the dev-shell fallback. Remove the false claim that the log/ directory is created automatically at startup — no code does this; document that it must be created manually.
…ing; clean up app docs knowledge-graph-database-guide.md: - Add forward-reference under Multiple Inheritance noting that conflict resolution will be provided through a future enhancement to relations; until then local values take priority (item B resolved) - Add Construction Order section (item A, applied earlier this session) TASKS.md: - Full rewrite as a clean public-facing task list - Remove session notes, internal history, applied-correction log, and resume token - Renumber tasks 1-5 (graphdb workers, non-normal start, code_change, old directories, start_phases) apps/graphdb/CLAUDE.md, apps/database/CLAUDE.md: - Replace TASKS.md Alignment sections with concise Remaining Work pointers apps/dictionary/CLAUDE.md: - Fix Files table (remove dict_wkr.erl and dictionary_draft.erl; add dictionary_server.erl and term_server.erl which are the actual files) - Remove Known Bugs section (sfiles bug was fixed; draft file note stale) - Remove TASKS.md Alignment section apps/nref/CLAUDE.md: - Update NYI status task references to new numbering (task 2, task 3) - Remove fixed-bugs list and superseded item CLAUDE.md (root): - Remove TASKS.md Alignment section; replace with Remaining Work pointer - Remove stale TASKS.md item reference from nref_include note
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.
Provided a descriptive summary of the whole knowledge graph database. Clarity of this project based on this documentation.