Fix a failing check

Your pull request is red on manni graph check and you did not write the rule. This page gets you green. You do not need to know what a triple is, and you will not have to open a Turtle file.

Read the line

warning: docs/configuration.md, docs/getting-started.md: Pages spell this concept two ways: "Installation" and "installation". Use one spelling on every page that names it.
  at https://example.com/dd/concept/installation skos:prefLabel
  manni:graph-shapes:1.3.0 Concept-prefLabel-collision: One name per language, so search and the glossary agree on a spelling.
  Guide: https://hawkeyexl.github.io/manni/graph/fix/

Read the first line first. It says everything you need to edit:

Part	What it is
warning	The severity. error fails the build; warning and notice report and exit 0.
docs/configuration.md, docs/getting-started.md	The pages the finding came from. This is where you edit. (no page) means it came from none.
The message	What is wrong, and what to change. It names the frontmatter key in backticks.

The lines under it are for when the message is not enough:

Line	What it is
at https://example.com/dd/concept/installation skos:prefLabel	The focus node, the graph’s name for the thing that failed, and the property the rule is about.
manni:graph-shapes:1.3.0 Concept-prefLabel-collision: …	The shapes file, the rule that judged it, and what the rule is for.
Guide:	This page.

To see every key a shape asks for, run npx @hawkeyexl/manni graph shapes show <shape>, with the shape’s name, such as ConceptShape. Add -f markdown for a frontmatter skeleton to copy.

A graph finding is emergent by nature. Two pages spelling one concept differently collide on a single node, so the fix is usually in one of them and the report names both. Nobody broke it on their own, which is also why this one is not necessarily yours to fix alone.

Reproduce it locally

No key, no network, no cache:

$ npx @hawkeyexl/manni graph build
$ npx @hawkeyexl/manni graph check

build writes the graph; check validates it. Run them in that order every time. check reads the file build wrote, so checking without building validates whatever was there before.

If the CI job also ran graph stats --check, run that too.

The common findings

Pages spell a concept two ways

Two pages named one concept with different spellings, such as Installation and installation, or CLI and Cli. They slug to the same node. It then has two preferred labels, and a reader of the graph cannot tell which is right.

Pick one spelling and use it in both pages. The report names both files, so this is a two-line change once you have decided which spelling wins. If the two really are different concepts, give them names that do not slug to the same thing.

A broader cycle

error: violations/alpha.md, violations/beta.md, violations/gamma.md: "Alpha" and "Beta" form a broader cycle, so each is its own ancestor. Remove one `broader` or `narrower` value on the cycle.
  at https://example.com/dd/concept/alpha skos:broader
  manni:graph-shapes:1.3.0 Concept-broader: A more general concept. A concept is never its own ancestor.
  Guide: https://hawkeyexl.github.io/manni/graph/fix/

Page A says its concept is narrower than B’s, and B says narrower than A’s. A concept cannot be its own ancestor.

The message names the concepts on the cycle. One of those broader or narrower values is wrong, usually the one added last. Remove or repoint it.

A mapping that points into the scheme

error: docs/glossary/pal.md, docs/glossary/pluggable-auth-layer.md, docs/guides/login.md: `exact-matches` names "token", a concept in this glossary. Use `broader`, `narrower` or `related-terms` for it instead.
  at https://example.com/graph/concept/pluggable-auth-layer skos:exactMatch
  manni:graph-shapes:1.3.0 Concept-exactMatch: The same concept in another vocabulary, from the term page. It never points into this glossary.
  Guide: https://hawkeyexl.github.io/manni/graph/fix/

A term’s match field names a concept of this graph’s own scheme. The mapping properties link to concepts in other vocabularies. Inside one scheme the relation is broader, narrower or related-terms, so move the value to the field that says how the two concepts relate.

A variant or an aspect in both lists

error: violations/alpha.md: The page lists a variant in both `applies-to` and `not-applicable-to`. Keep it only in the one that is true.
  at https://example.com/dd/doc/violations/alpha.md graph:notApplicableToVariant
  manni:graph-shapes:1.3.0 Document-notApplicableToVariant: The product variants the page does not apply to. A variant cannot be in both lists.
  Guide: https://hawkeyexl.github.io/manni/graph/fix/

The page says it applies to a product variant and also that it does not. Decide which is true and delete the other. Both lists are in the page’s graph: block. The same finding names about-product-aspect and not-about-product-aspect when an aspect sits in both. When it opens with A section in graph.sections, the two lists are under that section’s heading key instead.

A variant spelled two ways

error: docs/variant-lower.md, docs/variant-upper.md: Pages spell this variant two ways in `applies-to` or `not-applicable-to`. Use one spelling on every page.
  at https://example.com/graph/product/sp-x100 dcterms:title
  manni:graph-shapes:1.3.0 ProductVariant-title: The variant's name, as pages spell it in applies-to and not-applicable-to.
  Guide: https://hawkeyexl.github.io/manni/graph/fix/

One page writes sp-x100 and another SP-X100. Both name one variant, which then has two names. Pick the spelling your product uses and write it on every page the finding names.

A language name where a tag belongs

error: l10n-invalid/install.md: Set `lang` to a language tag such as `de` or `pt-BR`, not a language name.
  at https://example.com/dd/doc/l10n-invalid/install.md dcterms:language
  manni:graph-shapes:1.3.0 Document-language: The language the page is written in. Search, filters and per-language indexes group pages by it.
  Guide: https://hawkeyexl.github.io/manni/graph/fix/

1 error, 0 warnings, 0 notices

The page says lang: German. Write the tag instead, lang: de. A tag is a language code, with a region after a hyphen when it matters, as in pt-BR.

A predicate the shapes do not know

A finding that says manni wrote a property this shape does not list, on a node you did not write. The shapes are closed, so an unexpected property fails rather than passing unnoticed. The page is not at fault. A derive source started producing something the shapes have not learned. Hand it to whoever owns the shapes. It is a code change, in the same commit as the shapes update.

A sample question misses its page

warning: docs/limits.md: "How do I retry a failed upload?" does not find this page in the top 1 (it ranks 2; first is docs/retry.md)
  at https://example.com/graph/doc/docs/limits.md graph:sampleQuestion

The page lists the question under sample-questions, and a search for it ranks another page first. Read the page named after first is before you change anything.

• If that page answers the question, the question belongs to it. Move the question there.
• If this page answers it, put the question’s words where search weighs them most. That is the title, then the description, then the headings. A page that answers in other words than its reader asks in is hard to find.

it is not found means the search did not return the page at all. To see the whole ranking, run manni graph export search, then ask manni graph search the same question.

Broken internal link or section reference

From graph stats --check, not from check:

Broken internal links (1):
  docs/troubleshooting.md -> missing.md

Broken section refs (1):
  docs/getting-started.md -> #renamed-heading

The first is a link to a page that does not exist, usually a rename or a path written relative to the wrong directory. The second is a link to an anchor that does not exist, which is what a renamed heading leaves behind. Both name the page holding the link.

Coverage below threshold

  description              1/3  33.3%  ! below threshold

Your repository requires that share of pages to carry the field. If your pull request added pages, add the field to them. If it did not, the floor moved under you. That is a conversation with whoever set it rather than something to fix in your diff. See Coverage.

A schema error inside the graph: block

There is no graph validate. The block is checked by manni meta validate, against the page vocabulary:

✗ docs/install.md
    /graph  must NOT have additional property 'bogus'  (line 3)  [manni:graph:1.0.0]
      manni:graph:1.0.0 graph
      Guide: https://hawkeyexl.github.io/manni/meta/reference/schemas/manni-graph/

A typo inside the graph block, with the line number. The block is closed, so an unknown key is an error rather than an ignored one. Your repository puts the vocabulary in the schema set for these pages; see Checking a graph: block.

A warning about a page-level key

manni: docs/guide.md: page key "applies_to" is not read by manni graph and looks like "applies-to" — nothing was derived from it

This is a warning. It never fails a build, and it is worth knowing about. A page-level key that is nearly right derives nothing, silently, because a page may carry any key it likes. Rename it to the spelling in the message.

Exit codes

Code	What it means
0	Clean. Warnings and notices still exit 0.
1	Findings. Yours to fix, or the page author’s.
2	Operational. manni graph could not run at all. Not your problem. Hand it to the platform team.

An exit 2 reads as No input files matched, Invalid config in …, or an unknown flag value. None of those is about your page.

Still stuck

• Ask what the node is made of: npx @hawkeyexl/manni graph query --subject <the focus node from the message>
• Ask what reaches the page you edited: npx @hawkeyexl/manni graph traverse <page IRI> --reverse
• Read what the rule is for in Govern the graph, and the words in the glossary.