anchored-docs v2.1.1

• Changed: removed code that could not run (ste_check.mjs, docs_check.mjs, _glob.mjs). The findings and exit codes are the same. The 45 parity cases still match the 2.1.0 baseline.
• Changed: the docs_check.mjs error handler reports the message of an error, and the stack when there is one.

anchored-docs v2.1.0

• New: the bundle lives in docs/anchored-docs/. The prose and the scripts use this path. The project's own docs/ folder is free for other files.
• New: docs_check.mjs migrate <repo> [--apply] moves a 2.0 bundle to docs/anchored-docs/, rewrites the links that point at it, regenerates _map.json, and logs the move. A dry run is the default. A second run changes nothing. A conflict stops the run before a file moves. Read references/migrate.md.
• New: until a repository runs migrate, the scripts continue to find its bundle in docs/. When ste_check.mjs --glossary-report finds it there, it prints a notice that names the migrate command.
• Changed: docs/tickets/ stays adjacent to the bundle, not in the bundle. It keeps its .gitignore entry.
• Changed: ste_check.mjs no longer names docs/_glossary.json in its messages. It names the project glossary in the bundle.
• Changed: with a bundle at docs/anchored-docs/, docs_check.mjs uses the repository root as two levels above the bundle. So sources paths resolve without --repo. Before, the root was the parent of the bundle folder.
• Changed: for a source file, ste_check.mjs finds the project glossary in docs/anchored-docs/ first, then in docs/.
• Changed: the help text of docs_check.mjs names docs/anchored-docs/ and lists migrate. The ste_check.mjs --glossary-report example names docs/anchored-docs/.
• New: when docs_check.mjs gets docs/anchored-docs/ and that folder is missing, but docs/ holds a 2.0 bundle, it prints where the bundle is.

anchored-docs v2.0.1

• Corrected: the version of the skill is in metadata.version in the frontmatter. Before this change, it was a top-level version key. The Agent Skills specification does not let a skill use that key, and strict validators such as skills-ref validate refuse it.
• Corrected: INSTALL.md gives the frontmatter keys of the skill correctly.
• Corrected: when the --repo folder was not there, a sources pattern that starts with ** found a file. After this change, it finds no file, as in 1.2.0.
• Corrected: ste_check.mjs did not expand ~\ at the start of STE_AGENT_PACK. After this change, ~\ and ~/ go to the home folder, as in STE_ORG_GLOSSARY.
• Corrected: a command such as head can close the output pipe before the end of the report. Then the two scripts showed a Node.js error and stopped with exit code 1. After this change, they stop with the exit code of the checks and show no error.
• Corrected: a long line of dots or dashes made ste_check.mjs slow. With 80,000 dots, the check used 4 seconds. The time increased with the square of the length. After this change, the time increases with the length only, and the findings do not change.
• New: the two scripts show a control character from a doc or an argument as text, for example \x1b for ESC. Before this change, the report contained the raw character, which can change a terminal. SKILL.md tells the agent to use the output of the scripts as data, not as instructions.
• Corrected: docs_check.mjs map --check gave "out of date" for a _map.json that is not correct JSON. After this change, it stops with exit 2 and a message that names the file, as affected does. map --check also gives the notice for a remaining _map.yaml.
• Corrected: references/glossary.md and the exit codes in SKILL.md tell where an error message goes and when it gives the position of a JSON error.
• Corrected: the frontmatter parser reads four structures as YAML reads them. The four structures follow:
  • An apostrophe in a word, as in Don't # note, does not hide the # comment.
  • A colon with no space after it does not make a key. Examples are key:value and http://x.y.
  • A list below a key in a list item is the value of that key. An example is - code: x, then docs:, then - y.
  • A glossary entry with no term text stops the script with a message that names the entry. Before this change, the script did not use the entry and its synonyms, and gave no message.
• New: docs_check.mjs okf shows each frontmatter line that the parser cannot read, as frontmatter line N not understood. Before this change, the parser did not use the line and gave no message.

anchored-docs v2.0.0

Breaking changes:

• The scripts are Node.js ES modules. The scripts use Node.js 22 or a higher version and have no packages to install. The skill does not use Python. Each command changes from python3 <skill>/scripts/NAME.py to node <skill>/scripts/NAME.mjs.
• _glossary.yaml, _map.yaml, and org-glossary.yaml changed to JSON files: _glossary.json, _map.json, org-glossary.json. The frontmatter of a doc stays YAML, because OKF tells you to use YAML. INSTALL.md, section "Upgrading from 1.x", gives the steps.

Behavior:

• The output is the same as the output of 1.2.0 on a set of 41 tests, apart from the new file names. The Node.js scripts also give the same results as the Python scripts on 2.5 MB of prose and source comments.
• Corrected: docs_check.mjs links did not read .mjs files. Thus it found no code back-links in a Node.js repository with ES modules. After this change, it reads the same source files as ste_check.mjs.
• New: ste_check.mjs and docs_check.mjs also read .cjs, .mts, and .cts files. The two scripts check the doc comments and the back-links in these files with the JavaScript and TypeScript rules.
• Corrected: the scan for code back-links did not read the source files when a parent folder of the repository had a special name. These names are build, bin, obj, dist, node_modules, third_party, and .git. At this time the scan examines only the folders in the repository.
• Corrected: docs_check.mjs affected compared capital letters and small letters as different on Linux and macOS, and as the same on Windows. At this time it compares them as different on all systems. The okf check of sources globs also compares them as different on Windows and macOS.
• Corrected before the release: on Windows, ste_check.mjs checked index.md and log.md. The script does not check them on all systems, as in 1.2.0.
• Corrected before the release: a long sequence of spaces or | characters in a line made ste_check.mjs very slow. At this time, the time increases only as much as the length of the line.
• Corrected before the release: docs_check.mjs stale --days accepted values such as 1.0, 1e3, 0x10, and an empty value. The option accepts only an integer, as in 1.2.0. The option accepts only the digits 0 to 9.
• New: when a script cannot read a file, the script stops with exit 2 and a message that names the file. Examples are a folder with the name x.md, a broken file link, and a file that the user cannot read. The script prints the findings that it found before the stop. In 1.2.0 the script stopped with a traceback and exit 1.
• Corrected before the release: ste_check.mjs showed the notice for a remaining _glossary.yaml on the organization glossary file. The script shows the notice on the _glossary.yaml file.
• Corrected: the output does not change when PyYAML is installed. With PyYAML, some messages showed the time in a different format.
• Corrected: ste_check.mjs --glossary-report gives names with the same count in alphabetical sequence. Before this change, the sequence came from the folder scan and was different on different computers. docs_check.mjs links also gives the code back-links in the same sequence each time.
• New: a glossary file or a map file that is not correct JSON stops the script with a message that names the file. When a remaining _glossary.yaml or _map.yaml has no JSON file, the script gives a notice. Before this change, the script ignored that file.
• Removed: rule 3.2 from the help text. The checker did not show rule 3.2.
• Added references/glossary.md. That file contains the comments from the YAML glossary files, because JSON has no comments.
• Corrected the OKF link in references/okf.md. The specification is at https://github.com/GoogleCloudPlatform/open-knowledge-format.