chore: add remark markdown linting and fix docs

Why:

Keep markdown style consistent and catch issues automatically.

What:

- Add remark tooling, ignore build dirs, and reformat docs to match rules.

Author: doguabaris

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,14 +1,15 @@
----
+***
+
 name: Feature request
 about: Suggest an idea for this project
 title: ''
 labels: ''
 assignees: ''
 
----
+***
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. Ex. I'm always frustrated when \[...]
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.

.remarkignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+temp/
+coverage/
+tests/

CHANGELOG.md

@@ -1,2 +1,3 @@
 # v0.1.0-alpha.1 / 2025-11-15
-- Initial release.
+
+* Initial release.

CODE_OF_CONDUCT.md

@@ -116,7 +116,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+https://www.contributor-covenant.org/version/2/0/code\_of\_conduct.html.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).

CONTRIBUTING.md

@@ -5,20 +5,20 @@ improving documentation, or just giving feedback, it’s all welcome.
 
 ## How to Contribute
 
-- Open an [issue](https://github.com/GWALN/cli/issues) and describe what’s going on.
+* Open an [issue](https://github.com/GWALN/cli/issues) and describe what’s going on.
 
-- Fork the repo -> create a new branch -> commit changes -> open a PR.
+* Fork the repo -> create a new branch -> commit changes -> open a PR.
   Keep commits focused and descriptive.
 
-- Typos, clarity, formatting, everything counts. You can edit directly and open a PR.
+* Typos, clarity, formatting, everything counts. You can edit directly and open a PR.
 
-- Before submitting a PR, run local tests and verify expected CLI behavior with the mock API.
+* Before submitting a PR, run local tests and verify expected CLI behavior with the mock API.
 
 ## Resources
 
-- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
-- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
-- [GitHub Help](https://help.github.com)
+* [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
+* [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
+* [GitHub Help](https://help.github.com)
 
 ## License
 

README.md

@@ -1,9 +1,9 @@
 ![Image](https://github.com/user-attachments/assets/3152cf8b-b683-4acf-ab9d-e3bfd5dc0390)
 
-> [!NOTE]  
+> \[!NOTE]\
 > Originally built for the **DKGcon2025 Hackathon** powered by OriginTrail.
 
-## GWALN CLI
+## GWALN
 
 This tool helps you compare Grokipedia and Wikipedia topics. It parses
 structured snapshots, computes discrepancies, and drafts Community Notes
@@ -36,15 +36,15 @@ whether to publish.
 
 Before using this tool, you should be familiar with:
 
-- Basic command-line usage and Node.js tooling.
-- OriginTrail concepts, including DKG nodes and Knowledge Assets.
+* Basic command-line usage and Node.js tooling.
+* OriginTrail concepts, including DKG nodes and Knowledge Assets.
 
 You should have:
 
-- Node.js 18 or later on macOS, Linux, or Windows.
-- Network access to a DKG edge node and sufficient blockchain funds if
+* Node.js 18 or later on macOS, Linux, or Windows.
+* Network access to a DKG edge node and sufficient blockchain funds if
   you plan to publish.
-- Optional: a Google Gemini API key if you use automated bias
+* Optional: a Google Gemini API key if you use automated bias
   verification.
 
 ## How to use GWALN CLI
@@ -74,6 +74,7 @@ You should have:
 ### Fetch topic snapshots
 
 1. Select a topic ID from `topics.json` (for example, `moon`).
+
 2. Download raw Wikipedia data:
 
    ```bash
@@ -125,6 +126,7 @@ You should have:
    ```
 
 2. Inspect the output in `notes/moon.json` and `notes/index.json`.
+
 3. Publish to OriginTrail (ensure your config has live signing keys):
 
    ```bash
@@ -171,11 +173,11 @@ logic.
 
 Each MCP tool mirrors the CLI flags:
 
-- `fetch`: `{ source?, topicId? }`
-- `analyze`: `{ topicId?, force?, biasVerifier?, geminiKey?, geminiModel?, geminiSummary?, verifyCitations? }`
-- `notes`: discriminated union for `build`, `publish`, or `status`
-- `publish`: `{ filePath? , payload?, privacy?, endpoint?, environment?, ... }`
-- `show`: `{ topicId, renderHtml? }`
+* `fetch`: `{ source?, topicId? }`
+* `analyze`: `{ topicId?, force?, biasVerifier?, geminiKey?, geminiModel?, geminiSummary?, verifyCitations? }`
+* `notes`: discriminated union for `build`, `publish`, or `status`
+* `publish`: `{ filePath? , payload?, privacy?, endpoint?, environment?, ... }`
+* `show`: `{ topicId, renderHtml? }`
 
 Because the MCP server calls the same workflow modules as the CLI,
 cached files, Gemini credentials, and `.gwalnrc.json` are honored
@@ -214,15 +216,17 @@ This retrieves the assertion and optional metadata, displays them in the termina
 ## Troubleshooting
 
 `Analysis not found for topic`
-- Run both `gwaln fetch wiki --topic <id>` and `gwaln fetch grok --topic <id>` before analyzing.
+
+* Run both `gwaln fetch wiki --topic <id>` and `gwaln fetch grok --topic <id>` before analyzing.
 
 `DKG publish failed: UNAUTHORIZED`
-- Ensure `.gwalnrc.json` contains valid `dkgPrivateKey`, `dkgPublicKey`, and endpoint values; confirm the key has sufficient balance on the target chain.
+
+* Ensure `.gwalnrc.json` contains valid `dkgPrivateKey`, `dkgPublicKey`, and endpoint values; confirm the key has sufficient balance on the target chain.
 
 ## How to get help and report issues
 
-- Report issues at the GitHub issue tracker for this repository.
-- Ask questions by opening a discussion or contacting the maintainers on
+* Report issues at the GitHub issue tracker for this repository.
+* Ask questions by opening a discussion or contacting the maintainers on
   the project chat. You can expect a response within one week.
 
 ## Developer documentation
@@ -237,27 +241,27 @@ handled by a custom module that converts Wikipedia wikitext and
 Grokipedia HTML into identical structured JSON (lead/sections, sentences,
 claims, citations, media attachments). The analyzer stage:
 
-- normalizes sentences into token sets and compares them to detect
+* normalizes sentences into token sets and compares them to detect
   missing or extra context
-- aligns sections and claims using cosine similarity from the
+* aligns sections and claims using cosine similarity from the
   `string-similarity` library
-- computes numeric discrepancies via relative-difference heuristics and
+* computes numeric discrepancies via relative-difference heuristics and
   entity discrepancies via set symmetric differences
-- flags bias/hallucination cues through lexicon scans plus
+* flags bias/hallucination cues through lexicon scans plus
   subjectivity/polarity scoring
 
 Optional verification hooks call the Gemini API for bias confirmation and
 run citation checks against Grokipedia references.
 
 ### Code structure
 
-- `src/commands/`: CLI entry points (`init`, `fetch`, `analyse`, `show`,
+* `src/commands/`: CLI entry points (`init`, `fetch`, `analyse`, `show`,
   `notes`, `topics`, `publish`, `query`).
-- `src/lib/`: reusable modules including the parser, analyzer,
+* `src/lib/`: reusable modules including the parser, analyzer,
   discrepancies, bias metrics, and DKG helpers.
-- `data/`: cached structured snapshots per topic.
-- `analysis/`: analyzer outputs (JSON + HTML report).
-- `notes/`: JSON-LD Community Notes and index metadata.
+* `data/`: cached structured snapshots per topic.
+* `analysis/`: analyzer outputs (JSON + HTML report).
+* `notes/`: JSON-LD Community Notes and index metadata.
 
 ### Local development
 
@@ -288,23 +292,23 @@ run citation checks against Grokipedia references.
 
 #### Build and test
 
-- Build:
+* Build:
 
   ```bash
   npm run build
   ```
 
-- Run tests:
+* Run tests:
 
   ```bash
   npm test
   ```
 
 #### Debugging
 
-- `Analysis not found`: check `data/wiki` and `data/grok` for missing
+* `Analysis not found`: check `data/wiki` and `data/grok` for missing
   snapshots; rerun `gwaln fetch`.
-- `Publish timeout`: increase `publishMaxRetries` or verify the DKG node
+* `Publish timeout`: increase `publishMaxRetries` or verify the DKG node
   endpoint is reachable; use `--dry-run` to ensure the payload is valid
   before retrying.
 

SECURITY.md

@@ -5,6 +5,7 @@
 If you discover a security vulnerability in this package, please report it by emailing **abaris@null.net**. Please do not disclose the vulnerability publicly until we have had a chance to address it.
 
 ### Steps to Report:
+
 1. Provide a detailed description of the vulnerability.
 2. Include steps to reproduce the issue.
 3. Suggest possible fixes if applicable.

docs/analyzer-overview.md

@@ -9,10 +9,10 @@ the internals or explain them to other contributors.
 
 ### Snapshot fetchers
 
-- `gwaln fetch wiki` downloads the wikitext of a topic using
+* `gwaln fetch wiki` downloads the wikitext of a topic using
   `?action=raw` and records revision metadata, canonical URLs, and page
   languages.
-- `gwaln fetch grok` requests the Grokipedia article, converts HTML
+* `gwaln fetch grok` requests the Grokipedia article, converts HTML
   to Markdown with Turndown, removes Grok-specific header banners, and
   retrieves citation metadata through
   `https://grokipedia.com/api/page`.
@@ -25,15 +25,15 @@ The CLI stores both outputs under `data/wiki/<topic>.parsed.json` and
 The parser converts each source into a shared `StructuredArticle`
 representation:
 
-- Lead and section blocks with identifiers, anchor names, levels, and
+* Lead and section blocks with identifiers, anchor names, levels, and
   parent references.
-- Sentences with normalized text, token lists, citation/media references,
+* Sentences with normalized text, token lists, citation/media references,
   and backreferences to claim records.
-- Claims (one per sentence) that capture entity labels, normalized
+* Claims (one per sentence) that capture entity labels, normalized
   numbers, optional time hints, and supporting citations.
-- Media registry entries (title, caption, alt text, usage context, and
+* Media registry entries (title, caption, alt text, usage context, and
   license placeholders).
-- Reference store entries built from `<ref>` tags, Markdown links, and
+* Reference store entries built from `<ref>` tags, Markdown links, and
   Grokipedia API citations.
 
 The parser also removes leftover Grok header sentences to keep the
@@ -48,15 +48,15 @@ content scientific.
 3. The analyzer records total missing and extra sentences, while showing
    only the first five snippets for readability.
 4. **Similarity metrics:**
-   - **Word similarity:** Token overlap ratio between the two texts,
+   * **Word similarity:** Token overlap ratio between the two texts,
      measuring vocabulary overlap. This calculates how many words are
      shared between Wikipedia and Grokipedia regardless of sentence
      structure.
-   - **Sentence similarity:** Proportion of matching sentences,
+   * **Sentence similarity:** Proportion of matching sentences,
      combining identical sentences (full weight) and reworded
      sentences (50% weight). This measures structural alignment at the
      sentence level.
-   - **N-gram overlap:** Uses shingle size 4 to capture contiguous
+   * **N-gram overlap:** Uses shingle size 4 to capture contiguous
      phrase matches.
 
 ### Understanding similarity metrics
@@ -72,8 +72,9 @@ phrased distinctly.
 
 **Sentence similarity** measures structural alignment—how many complete
 sentences match between sources. This metric counts:
-- Identical sentences at full weight (1.0)
-- Reworded sentences at half weight (0.5)
+
+* Identical sentences at full weight (1.0)
+* Reworded sentences at half weight (0.5)
 
 A low sentence similarity (e.g., 0.2%) despite high word similarity
 reveals that sources cover the same topic but express information
@@ -90,30 +91,30 @@ sentence pairs.
 
 ### Alignment helpers (`src/lib/alignment.ts`)
 
-- **Sections:** headings are compared with cosine similarity
+* **Sections:** headings are compared with cosine similarity
   (`string-similarity`). Matches above 0.7 get linked; unmatched headers
   become missing/extra sections.
-- **Claims:** sentence text uses the same cosine check with a 0.65
+* **Claims:** sentence text uses the same cosine check with a 0.65
   threshold. Unmatched Grok claims indicate hallucinations. Unmatched
   Wiki claims indicate missing context.
 
 ### Discrepancy detection (`src/lib/discrepancies.ts`)
 
-- **Numeric differences:** the analyzer compares the first number in each
+* **Numeric differences:** the analyzer compares the first number in each
   aligned claim and flags deviations when
   `|a - b| / max(|a|, |b|)` exceeds 5% and units match.
-- **Entity differences:** normalized entity sets (trimmed, lowercase) are
+* **Entity differences:** normalized entity sets (trimmed, lowercase) are
   compared using symmetric difference to catch missing actors or places.
-- **Media and citation differences:** set comparisons reveal files or
+* **Media and citation differences:** set comparisons reveal files or
   URLs present in only one source.
 
 ### Bias and hallucination cues
 
-- MOS "words to watch" trigger events only when Grokipedia uses the term
+* MOS "words to watch" trigger events only when Grokipedia uses the term
   and Wikipedia does not.
-- Subjectivity and polarity deltas come from token ratios in
+* Subjectivity and polarity deltas come from token ratios in
   `src/lib/bias-metrics.ts`.
-- Optional verification hooks call Gemini to cross-check bias events and
+* Optional verification hooks call Gemini to cross-check bias events and
   confirm whether extra sentences cite valid references.
 
 ### Diff and highlights
@@ -126,35 +127,35 @@ HTML views.
 
 Analyzer results land in the `gwaln.analysis/2` schema. Each JSON file includes:
 
-- **Stats:** character counts, sentence totals, and missing/extra counts.
-- **Similarity ratios:** structured as an object containing:
-  - `word`: vocabulary overlap ratio (0.0 to 1.0)
-  - `sentence`: sentence-level match ratio (0.0 to 1.0)
-- Alignment arrays for sections and claims with similarity scores.
-- Numeric and entity discrepancy lists.
-- Bias metrics, bias/hallucination events, diff samples, and optional
+* **Stats:** character counts, sentence totals, and missing/extra counts.
+* **Similarity ratios:** structured as an object containing:
+  * `word`: vocabulary overlap ratio (0.0 to 1.0)
+  * `sentence`: sentence-level match ratio (0.0 to 1.0)
+* Alignment arrays for sections and claims with similarity scores.
+* Numeric and entity discrepancy lists.
+* Bias metrics, bias/hallucination events, diff samples, and optional
   verifier responses.
-- Confidence labels derived from word similarity and discrepancy density.
+* Confidence labels derived from word similarity and discrepancy density.
 
 ### Caching
 
 Each run records the analyzer version, shingle size, and cache TTL.
 `analysis/<topic>.json` files are cached through
 `src/shared/analysis-cache.ts`. Entries stay "fresh" when:
 
-- the `content_hash` (based on a MediaWiki-style hash of the combined
+* the `content_hash` (based on a MediaWiki-style hash of the combined
   wiki and Grok text) matches the current sources, and
-- the timestamp falls within the TTL (72 hours by default).
+* the timestamp falls within the TTL (72 hours by default).
 
 When either condition fails, the analyzer recomputes the report.
 
 ## Presentation and publishing
 
-- `gwaln show` prints a terminal summary and can open an HTML
+* `gwaln show` prints a terminal summary and can open an HTML
   dashboard that surfaces the same metrics in a flat layout.
-- `gwaln notes build` generates JSON-LD ClaimReviews with annotation
+* `gwaln notes build` generates JSON-LD ClaimReviews with annotation
   targets referencing both sources.
-- `gwaln notes publish` signs and uploads the ClaimReview to the
+* `gwaln notes publish` signs and uploads the ClaimReview to the
   OriginTrail DKG, records the returned UAL, and logs publish details.
 
 ## Typical workflow