stack: TOC-Scope auf types/ und docs/, Sprachregeln nach AGENTS.md zentralisiert, alle Templates auf Control-Plane-Sprache, --breaking akkumuliert (schliesst #99)
Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
This commit is contained in:
+51
-37
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: types/type-spec.md
|
||||
name: entity
|
||||
description: Basistyp für Entity-Seiten - Projekte, Systeme, Werkzeuge, Technologien oder Personen
|
||||
description: Base type for entity pages - projects, systems, tools, technologies or people
|
||||
schema: types/entity.schema.yaml
|
||||
subtype_field: entity_type
|
||||
base_dir: entities
|
||||
@@ -16,47 +16,61 @@ layout:
|
||||
|
||||
# Entity
|
||||
|
||||
`entity` ist der Typ für konkrete Dinge: Projekte, Systeme, Werkzeuge, Technologien oder Personen. Entities sind die primären Bausteine des Wissensgraphen.
|
||||
`entity` is the type for concrete things: projects, systems, tools, technologies or people. Entities are the primary building blocks of the knowledge graph.
|
||||
|
||||
## Wann zu verwenden
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- Darstellung eines Softwareprojekts, einer Initiative oder eines Arbeitsvorhabens
|
||||
- Dokumentation eines betriebenen Systems, Dienstes oder einer Infrastrukturkomponente
|
||||
- Beschreibung eines CLI-Werkzeugs, Hilfsprogramms oder einer Programmbibliothek
|
||||
- Festhalten von Informationen zu einer Sprache, einem Framework oder einem Protokoll
|
||||
- Dokumentation einer Person, eines Teams oder einer Organisation
|
||||
- [When to use](#when-to-use)
|
||||
- [When NOT to use](#when-not-to-use)
|
||||
- [Frontmatter](#frontmatter)
|
||||
- [Authoring guidance](#authoring-guidance)
|
||||
- [Template](#template)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Wann NICHT zu verwenden
|
||||
## When to use
|
||||
|
||||
- Für abstrakte Konzepte, Muster oder Methodiken (dann `concept`)
|
||||
- Für Quelldokumente oder eingelesenes Material (dann `source`)
|
||||
- Für vergleichende Analysen (dann `comparison`)
|
||||
- Representing a software project, an initiative or a piece of work
|
||||
- Documenting a running system, service or infrastructure component
|
||||
- Describing a CLI tool, utility or software library
|
||||
- Recording information about a language, a framework or a protocol
|
||||
- Documenting a person, a team or an organization
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- For abstract concepts, patterns or methodologies (use `concept`)
|
||||
- For source documents or ingested material (use `source`)
|
||||
- For comparative analyses (use `comparison`)
|
||||
|
||||
## Frontmatter
|
||||
|
||||
| Feld | Pflicht | Verwendung |
|
||||
| Field | Required | Use |
|
||||
|---|---:|---|
|
||||
| `type` | Ja | `types/entity.md` |
|
||||
| `entity_type` | Ja | Eines von: project, system, tool, technology, person |
|
||||
| `tags` | Nein | Navigations-Tags zur Kategorisierung |
|
||||
| `created` | Ja | Erstellungsdatum (YYYY-MM-DD) |
|
||||
| `modified` | Ja | Datum der letzten Änderung (YYYY-MM-DD) |
|
||||
| `related` | Nein | Titel verwandter Seiten (Entities, Concepts, Sources) |
|
||||
| `sources` | Nein | Titel der Source-Seiten, die die Aussagen dieser Seite stützen |
|
||||
| `provenance` | Ja | sourced, general oder mixed |
|
||||
| `summary` | Ja | Einzeiler für `kb/index.md` |
|
||||
| `type` | Yes | `types/entity.md` |
|
||||
| `entity_type` | Yes | One of: project, system, tool, technology, person |
|
||||
| `tags` | No | Navigation tags for categorization |
|
||||
| `created` | Yes | Creation date (YYYY-MM-DD) |
|
||||
| `modified` | Yes | Date last changed (YYYY-MM-DD) |
|
||||
| `related` | No | Titles of related pages (entities, concepts, sources) |
|
||||
| `sources` | No | Titles of the source pages backing this page's claims |
|
||||
| `provenance` | Yes | sourced, general or mixed |
|
||||
| `summary` | Yes | One-liner for `kb/index.md` |
|
||||
|
||||
## Autorenanweisungen
|
||||
## Authoring guidance
|
||||
|
||||
- Der Titel ist der kanonische Name der Entity und folgt der etablierten Bezeichnung des Gegenstands, nicht der KB-Sprache (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" und "Language")
|
||||
- Die Hauptbeschreibung steht weit oben
|
||||
- Auf verwandte Entities und Concepts verlinken, wo Beziehungen bestehen
|
||||
- Bei `provenance: sourced` oder `mixed` harte Fakten inline mit einer `[^cite-id]`-Fußnote belegen -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` erzeugt Id und Definition
|
||||
- Wikipedia-Tonfall: sachlich, neutral, keine Werbesprache
|
||||
- The title is the entity's canonical name and follows the subject's established designation, not the KB language (`kb/CONTRACT.md` § "Titles are identifiers", `kb/CONVENTIONS.md` §§ "Naming" and "Language")
|
||||
- The main description goes near the top
|
||||
- Link to related entities and concepts wherever relationships exist
|
||||
- Under `provenance: sourced` or `mixed`, back hard facts inline with a `[^cite-id]` footnote -
|
||||
`tools/wikitool cite add --page "<Title>" --source "Source - X"` mints the id and its definition
|
||||
- Wikipedia register: factual, neutral, no marketing language
|
||||
|
||||
## Template
|
||||
|
||||
The block below is page material, so it is written in this instance's KB language
|
||||
(`kb/CONVENTIONS.md` `language:`) rather than in the control plane's English - its headings
|
||||
become the headings of every page `wikitool new entity` scaffolds.
|
||||
|
||||
```markdown
|
||||
# {name}
|
||||
|
||||
@@ -84,15 +98,15 @@ TODO: Ausführliche Informationen, nach sinnvollen Abschnitten gegliedert
|
||||
- [{today}] - Page created via wikitool
|
||||
```
|
||||
|
||||
Der Beziehungsabschnitt steht bewusst **nicht** im Template: er ist eine generierte Region, die
|
||||
`wikitool xref` beim ersten Kanteneintrag zwischen Markern anlegt und aus `related:` neu
|
||||
rendert. Ein Autor schreibt dort nie hinein. Der Wert hinter `**Typ:**` bleibt der englische
|
||||
Enum-Wert - danach filtert `search --field`.
|
||||
The relationships section is deliberately **not** in the template: it is a generated region that
|
||||
`wikitool xref` creates between markers on the first edge entry and re-renders from `related:`.
|
||||
An author never writes into it. The value behind `**Typ:**` stays the English enum value - that is
|
||||
what `search --field` filters on.
|
||||
|
||||
---
|
||||
|
||||
Ergänzende Hinweise:
|
||||
Additional notes:
|
||||
|
||||
- Entity-Seiten bilden den konkreten Bestand der Wissensbasis
|
||||
- Jeder Entity-Typ (project, system, tool usw.) ist eine Ausprägung dieses Basistyps
|
||||
- Die Beziehungen zwischen Entities tragen die Vernetzung des Wissensgraphen
|
||||
- Entity pages form the concrete inventory of the knowledge base
|
||||
- Every entity type (project, system, tool and so on) is a variant of this base type
|
||||
- The relationships between entities carry the knowledge graph's interconnection
|
||||
|
||||
Reference in New Issue
Block a user