diff --git a/pages/AGENTS.md b/pages/AGENTS.md new file mode 100644 index 0000000000..8a1b0367bf --- /dev/null +++ b/pages/AGENTS.md @@ -0,0 +1,186 @@ +# Wiki Content Guide + +## Purpose + +This Grav wiki manages final theses, semester projects, and internships. Treat its pages as long-lived supervision records rather than polished articles: preserve factual history, make current work easy to find, and distinguish recorded facts from proposed work. + +The main content areas are: + +- `topics/`: support materials and general project summaries. +- `interns/`: intern profiles. +- `students//`: student profiles grouped by the year in which the student started studying. + +## General editing rules + +- Preserve the language already used by a page. Student profiles are usually in Slovak; intern profiles may be in English. Use the page's language for new headings and text. +- Preserve valid Grav YAML front matter between `---` delimiters. Do not rename existing taxonomy keys. +- Treat `taxonomy.author` as the supervisor, `taxonomy.tag` as project keywords, and `taxonomy.category` as project-type/year categories such as `bp2027`, `dp2027`, or `vp2026`. +- Use lowercase `first_last` profile directory names without diacritics. Keep the person's correct spelling and diacritics in the front-matter `title`. +- Do not invent names, dates, assignments, status updates, completed work, repository URLs, results, or citations. If required information is missing, leave an explicit placeholder or ask for it. +- Keep links descriptive. Every active student project should have a visible link to its Git repository. Do not mistake a linked dependency, article, dataset, or related project for the student's repository. +- Prefer focused edits. Do not reformat or reorganize a legacy profile unless the task requires it. +- Apply the canonical formats below to new profiles and substantial new project sections. When updating an existing section, follow its established style unless doing so would make the record ambiguous. + +## Finding and comparing projects + +When searching for a person or project, search across `students/`, `interns/`, and `topics/`, not only the newest cohort. Check: + +- profile names and project titles; +- front-matter categories, tags, and authors; +- assignment text, goals, meeting status, and task backlogs; +- Git repository links and links to related wiki topics. + +When identifying similar projects, explain the similarity using concrete evidence such as a shared task, domain, dataset, method, model, or evaluation approach. Separate direct predecessors from projects that are only thematically related. + +## Creating a student profile + +Create a profile at `students///README.md`. Use this baseline: + +```markdown +--- +title: Full Student Name +published: true +taxonomy: + category: [project_type_and_end_year] + tag: [keyword-one,keyword-two] + author: Supervisor Name +--- + +rok začiatku štúdia: YYYY + +# Project Type YYYY + +Názov: + +Project title + +Repozitár: + +- [Git repozitár](https://example.invalid/repository) + +Zadanie: + +1. First assignment point. +2. Second assignment point. +``` + +Replace all placeholders before publishing. The year in the project heading and taxonomy category is the project's expected ending year, not the study start year. Add every project represented on the profile to `taxonomy.category`. + +Common Slovak project/category names are: + +- `Bakalárska práca` / `bpYYYY` +- `Bakalársky projekt` / `bpYYYY` +- `Diplomová práca` / `dpYYYY` +- `Diplomový projekt` / `dpYYYY` +- `Vedecký projekt` / `vpYYYY` +- `Tímový projekt` / `tpYYYY` + +Follow an existing nearby profile when another established project type is needed. + +## Creating an intern profile + +Create a profile at `interns//README.md`. Intern pages normally use the language of supervision and this baseline: + +```markdown +--- +title: Full Intern Name +published: true +taxonomy: + category: [internship-program] + tag: [keyword-one,keyword-two] + author: Supervisor Name +--- + +Internship program and period + +Goal: + +- Primary goal + +Repository: + +- [Git repository](https://example.invalid/repository) + +Tasks: + +1. First task. +2. Second task. +``` + +Record the internship period instead of a student study-start year. Add results, reports, datasets, and model links when they become available. + +## Student project sections + +A student may have several semester or final projects in one profile. Each project section must make these items identifiable: + +- project type and ending year in the heading; +- project title; +- assignment or clearly marked preliminary assignment; +- Git repository link; +- goals or expected outputs when known; +- dated meeting records. + +Place the newest/current project first. Keep older project records because they provide context and make related work discoverable. + +Do not silently turn preliminary ideas into an approved assignment. Label tentative content with the page's existing terms, for example `Predbežné zadanie`, `Návrh`, `Možné ciele`, or `Nápady`. + +## Meeting records + +Add new meetings under the relevant project, newest first. Use the page's language. A Slovak record should normally look like: + +```markdown +Stretnutie DD.MM.YYYY + +Stav: + +- Work completed or current observed state. +- Important problem or result. + +Úlohy: + +- Concrete next action with an observable output. +- Another prioritized action. + +Zásobník úloh: + +- Lower-priority or possible future work. +``` + +An English intern record may use `Meeting`, `State`, `Tasks`, and `Future tasks`. Omit an empty optional backlog, but do not omit known status or assigned tasks. Preserve checkbox notation where a page already uses it; never mark a task complete without recorded evidence. + +## Writing assignments and proposing tasks + +Write project assignments as numbered, outcome-oriented points. A useful assignment normally progresses through: + +1. reviewing relevant methods and literature; +2. selecting or preparing data, tools, or an experimental setup; +3. implementing and evaluating the proposed solution; +4. identifying limitations and proposing improvements. + +Adapt that sequence to the actual project instead of copying generic wording unchanged. Keep the title, assignment, goals, tasks, and expected artifacts consistent. + +When proposing new tasks from a project status: + +- read the latest meeting and unresolved earlier tasks first; +- connect each proposal to a recorded problem, result, assignment point, or missing deliverable; +- prioritize the smallest verifiable next steps; +- include expected artifacts such as code, data, tables, experiment results, or written sections; +- reuse relevant methods or resources found in similar projects, with links; +- distinguish immediate tasks from optional ideas or backlog items; +- include updating the Git repository when code or data is produced, without requesting secrets or credentials. + +Do not claim that a proposed experiment will improve results. State what it is intended to test and how the result should be evaluated. + +## Review checklist + +Before finishing a content change, verify that: + +- front matter is valid YAML and retains `title`, `published`, and taxonomy data; +- the profile path and study-start year or internship period agree; +- every project heading and category uses the ending year; +- the person's name, supervisor, and keywords are present; +- each active student project has its title, assignment, and Git repository link; +- a new meeting has a date, status, and actionable tasks and is in newest-first order; +- proposed facts are not presented as recorded facts; +- internal and external links are syntactically valid; +- unrelated historical content and formatting were left intact.