# Knowledge And Skill Foundation

Version `0.1.R` defines how Agrarian treats knowledge, practice, body condition,
tools, and infrastructure before those systems become heavy gameplay code.

## MVP Separation Model

Agrarian should not collapse every form of progress into one generic skill
number. The MVP separates five related but distinct drivers.

Knowledge:

- Represents what a character understands.
- Comes from observation, teaching, notes, mistakes, questions, and practice
  reflection.
- Affects judgment, recognition, safety, sequencing, and when warnings appear.
- Should help players understand why something worked or failed.

Practical experience:

- Represents practiced execution under real conditions.
- Comes from repeated action, variation, failed attempts, recovery, and doing
  the work in different weather, light, terrain, and tool conditions.
- Affects speed, consistency, yield, precision, and waste.
- Should grow slowly from use and should not replace core understanding.

Physical stats:

- Represent the body in the moment: health, stamina, hunger, thirst, body
  temperature, exhaustion, injury, sickness, age, carry load, and care history.
- Affect what a character can safely do right now.
- Should create readable pressure without becoming a hidden knowledge system.

Tools:

- Represent external capability the player can hold, equip, place, or maintain.
- Affect what actions are possible, how safe they are, how much effort they
  require, and how good the result can be.
- Should still require knowledge and practice for best outcomes.

Infrastructure:

- Represents durable world improvements such as shelter, storage, paths, wells,
  fields, workshops, firebreaks, and community systems.
- Affects baseline safety, efficiency, capacity, and resilience.
- Should reduce routine survival pressure without removing consequences from
  poor choices.

MVP rule: basic survival actions must remain possible with low knowledge and
poor tools, but outcomes should be riskier, slower, lower quality, or more
wasteful until knowledge, practice, tools, and infrastructure improve.

## First-Pass Skill Taxonomy

The MVP skill taxonomy starts with practical survival domains the player uses in
the first hours of play. Each skill can later contain knowledge topics,
practice records, tool modifiers, environmental modifiers, and teaching hooks.

Survival:

- Core self-care, prioritization, risk recognition, rest, hydration, calories,
  warmth, and avoiding preventable injury.
- Early effects: better warning timing, fewer panic mistakes, and more reliable
  recovery choices.

Gathering:

- Identifying useful resources, harvesting safely, avoiding waste, and knowing
  when weather, light, terrain, or tool condition makes gathering risky.
- Early effects: better yield, lower injury risk, and less resource damage.

Tool use:

- Handling primitive tools safely, choosing the right tool, maintaining tools,
  and recognizing when improvised use is dangerous.
- Early effects: less stamina cost, fewer injuries, and more consistent work.

Crafting:

- Following recipes, sequencing steps, judging material suitability, and
  recognizing weak or unsafe results.
- Early effects: fewer failed crafts, less waste, and better item quality.

Fire:

- Ignition, fuel choice, containment, maintenance, extinguishing, smoke, warmth,
  wildfire risk, and using fire without burning structures or vegetation.
- Early effects: safer campfires, lower spread risk, and better warmth/cooking
  reliability.

Shelter:

- Site choice, wind/rain exposure, drainage, structural basics, maintenance,
  insulation, and avoiding fire or flood hazards.
- Early effects: better placement, more reliable protection, and fewer wasted
  materials.

Navigation:

- Reading terrain, weather, daylight, landmarks, slope, watercourses, and safe
  routes.
- Early effects: fewer dangerous detours, better route choice, and safer return
  to shelter.

First aid:

- Recognizing injury, bleeding, sprains, sickness, cold exposure, dehydration,
  and when rest or treatment matters.
- Early effects: earlier warnings, better treatment choices, and reduced
  recovery mistakes.

Food safety:

- Potable water, edible plant caution, spoilage awareness, cooking basics,
  contamination risk, and unsafe hunger-driven decisions.
- Early effects: fewer sickness triggers and better food/water decisions.

Weather awareness:

- Reading temperature, wind, rain, exposure, nightfall, storms, and shelter/fire
  implications.
- Early effects: earlier shelter/fire decisions and fewer exposure surprises.

Taxonomy rule: skills are not unlock gates for basic MVP survival actions. They
modify risk, quality, speed, yield, readability, and confidence.

## Knowledge Effects On Survival Actions

Knowledge should change outcomes in ways the player can understand. It should
not silently guarantee success or replace practical experience.

Fewer mistakes:

- Knowledge reduces obviously bad choices, such as placing fire near dry brush,
  drinking unsafe water without treatment, building shelter in a drainage path,
  ignoring nightfall, or using the wrong material for a recipe.
- The MVP expression is warning text, safer default prompts, and clearer failed
  action reasons.

Safer attempts:

- Knowledge lowers the chance that an attempt creates injury, sickness,
  uncontrolled fire, wasted materials, or exposure.
- The MVP expression is risk messaging and lower future failure modifiers once
  the player has learned the relevant concept.

Better yields:

- Knowledge helps a character identify the useful part of a resource and avoid
  damaging it during gathering, processing, or crafting.
- The MVP expression is improved expected yield or reduced waste where a system
  already has yield/waste hooks.

Lower injury risk:

- Knowledge teaches safe handling, body mechanics, weather caution, fire
  distance, tool choice, first-aid urgency, and when to stop working.
- The MVP expression is fewer avoidable injury checks and clearer warnings when
  hunger, thirst, darkness, fatigue, or bad weather make work unsafe.

More reliable outcomes:

- Knowledge improves sequencing and condition checks before the action begins.
- The MVP expression is fewer failed crafts, safer shelter placement, better
  fire maintenance, better water decisions, and more useful feedback after poor
  results.

Action-effect rule: knowledge should usually adjust probabilities, quality,
warnings, and explanation. It should only hard-block actions when the action
would be nonsensical without a discovered concept or required tool.

## Practical Experience Growth

Practical experience should grow from meaningful work, not from standing still
or repeating a zero-risk input forever. It is the record of a character learning
how a task feels in the world.

Use:

- Experience increases when a character performs a real survival action with
  cost, time, context, and outcome.
- Good candidates include gathering, tool use, crafting, fire maintenance,
  shelter placement, navigation decisions, first aid, food preparation, and
  weather-response choices.

Repetition:

- Repetition improves consistency, but repeated identical low-stakes actions
  should give diminishing returns.
- Variation should matter: different weather, darkness, tools, materials,
  terrain, injury state, and resource types teach more than the same easy action.

Mistakes:

- Mistakes can teach when they have a readable cause and the player receives
  feedback.
- Failed crafts, wasted resources, unsafe fire placement, bad shelter sites,
  injury, sickness, and exposure should create learning opportunities if the
  player can understand what happened.

Recovery from failure:

- Recovering from a bad outcome should teach more than simply failing.
- Examples include extinguishing a risky fire, treating bleeding, finding safer
  water, rebuilding a weak shelter, resting after exhaustion, and changing route
  after getting lost.

Experience gain rule: award experience for meaningful action plus context, apply
diminishing returns to rote repetition, and give recovery credit when a player
responds well to a mistake.

## First Contextual Learning Prompts

Contextual learning prompts should appear when the player is already interacting
with the relevant risk. They should be short, actionable, and easy to ignore
after the player understands the concept.

Fire safety:

- Trigger examples: placing or maintaining a campfire near dry brush, shelter,
  wood piles, high wind, or long burn duration.
- Prompt intent: explain clearance, containment, maintenance, extinguishing, and
  wildfire/structure risk.
- Example wording: "Clear space around open flame. Wind and dry fuel can spread
  fire."

Potable water:

- Trigger examples: interacting with unknown water, drinking while sick, or
  collecting water near contamination risk.
- Prompt intent: distinguish water access from safe drinking water.
- Example wording: "Water source found. Treating or boiling lowers sickness
  risk."

Exposure:

- Trigger examples: nightfall, rain, wind, low body temperature, soaked state,
  exhaustion, or leaving shelter/fire protection.
- Prompt intent: explain warmth, shelter, wind, rain, rest, and body temperature.
- Example wording: "Cold and wind drain warmth. Fire, shelter, dry clothes, and
  rest reduce exposure."

Shelter placement:

- Trigger examples: placing shelter in drainage, exposed wind, steep slope, too
  close to fire, or near unsafe terrain.
- Prompt intent: explain drainage, wind, fire distance, stability, and
  weather-protection tradeoffs.
- Example wording: "Shelter works best on stable, drained ground away from open
  flame."

Injury care:

- Trigger examples: bleeding, sprain, sickness, exhaustion, low health, or
  continuing heavy work while injured.
- Prompt intent: explain stop-work decisions, rest, treatment, and worsening
  risk.
- Example wording: "Treat bleeding and rest before heavy work. Exhaustion makes
  mistakes more likely."

Resource identification:

- Trigger examples: first focus on wood, stone, fiber, edible plants, hide, or
  water-related resources.
- Prompt intent: teach why the resource matters and what basic actions it
  supports.
- Example wording: "Fiber is useful for binding, panels, and early shelter
  parts."

Prompt rule: contextual prompts should explain the immediate risk or opportunity
without pausing the game or forcing a quiz.

## Optional Knowledge Checks

Optional knowledge checks should appear when a question naturally belongs to the
current action. They are not school-test popups and should not interrupt basic
survival.

Presentation rules:

- Show checks as optional inline choices, short reflection prompts, or camp/journal
  review cards.
- Let players continue basic survival without answering.
- Do not pause combat, weather danger, fire spread, or other time-sensitive
  events.
- Avoid repeated prompts after the player has recently answered, skipped, or
  demonstrated the concept through action.

When checks appear:

- Before a risky improvement path, such as safer fire setup, shelter siting,
  water treatment, advanced first aid, or higher-quality crafting.
- After a readable mistake, when the game can ask what likely went wrong.
- During calm moments near shelter, campfire, rest, journals, mentors, or
  teaching interactions.

Outcome rules:

- Correct answers can improve confidence, reduce future warnings, unlock clearer
  explanations, or slightly improve risk/quality modifiers.
- Wrong answers should explain the correction and may leave the player at normal
  baseline risk instead of punishing them harshly.
- Skipping should preserve basic action access.

Knowledge-check rule: checks should deepen understanding and improve outcomes,
not gate the first survival loop.

## Failed-Action And Poor-Result Feedback

When an action fails or produces a poor result, the player should receive a
plain explanation that points to the likely cause and next useful response. The
message should be short enough to read during play.

Feedback should identify:

- missing or unsuitable materials;
- unsafe weather, darkness, terrain, or exposure;
- low stamina, hunger, thirst, injury, sickness, or exhaustion;
- poor tool choice or damaged tools;
- low knowledge, low practical experience, or missed prerequisite concept;
- invalid placement, fire risk, drainage risk, blocked access, or instability;
- normal uncertainty when the game intentionally does not reveal exact odds.

Message style:

- Say what happened.
- Name one likely cause.
- Offer one useful next step.
- Avoid blaming the player.
- Avoid revealing hidden formulas or exact random rolls.

Example messages:

- "The fire catches poorly. Damp fuel and wind are making ignition unreliable."
- "The shelter frame feels unstable. Flatter, drained ground would help."
- "You waste some fiber. More practice with binding would improve the result."
- "Your hands shake from exhaustion. Rest or food would make this safer."

Feedback rule: poor results should teach the player what to try next without
turning every failure into a lecture.

## Learning Accessibility Rules

The learning system should support different players without making Agrarian
feel shallow. Accessibility here means readable, repeatable, and fair.

Hints:

- Hints should be available for basic survival concepts.
- Hints should become less frequent after the player demonstrates the concept.
- Players should be able to re-open important survival hints from a journal,
  help panel, or camp review surface.

Retries:

- Basic survival learning should allow retries after mistakes.
- Retrying should cost time, materials, stamina, safety, or opportunity where
  appropriate, but should not trap the player in a dead-end tutorial state.

Readable wording:

- Use plain language before technical vocabulary.
- Keep prompt text short during active play.
- Put deeper explanation in review/journal surfaces.
- Avoid color-only meaning for warnings and result quality.

No hard lockout from basic survival:

- Low knowledge should not block gathering, drinking, fire attempts, basic
  shelter attempts, or first aid attempts.
- Knowledge can improve safety and quality, but basic survival remains playable.

Non-punitive practice paths:

- Players should have safer ways to practice common concepts near camp, shelter,
  or low-risk resources.
- Practice can produce weaker outcomes without severe punishment.
- Practice should still avoid infinite exploit loops through diminishing returns.

Accessibility rule: learning should make players more capable without making
them feel trapped, shamed, or forced into a classroom flow.

## Subject Content Format

Learning content should use a small structured format so topics can become data
assets later without rewriting design intent.

Required fields:

- `topic`: stable identifier and display name, such as `fire.clearance`.
- `concepts`: one or more concept tags the player may learn or demonstrate.
- `difficulty_tier`: `elementary`, `practical`, `advanced`, or `expert`.
- `prerequisite_concepts`: concept tags that should be known first, if any.
- `in_game_effect`: the warning, modifier, feedback, unlock, or quality effect
  this topic can influence.
- `practice_action`: the action that can build practical experience for the
  topic.
- `source_note`: a short design/source note explaining why the topic matters.

Example:

```text
topic: fire.clearance
concepts: fire_safety, dry_fuel, wind_spread
difficulty_tier: elementary
prerequisite_concepts: none
in_game_effect: clearer fire-risk warning and lower unsafe-placement mistakes
practice_action: clear area, contain fire, maintain fire, extinguish fire
source_note: Open flame near dry fuel and wind can spread beyond the campfire.
```

Format rule: content records should be small enough to review in source control
and explicit enough to become data assets later.

## MVP Elementary Survival Question Bank

The first question bank is intentionally small and elementary. These questions
support optional checks, camp review, and future teaching objects.

```text
id: fire.clearance.001
topic: fire.clearance
question: Why clear dry brush away from a campfire?
answers: A) It lowers fire-spread risk. B) It makes the fire colder. C) It makes rain stronger.
correct: A
feedback: Open flame, dry fuel, and wind can spread fire beyond the campfire.
```

```text
id: water.potable.001
topic: water.potable
question: What is the safest first assumption about unknown water?
answers: A) It may need treatment. B) It is always safe. C) It restores warmth.
correct: A
feedback: Water access and safe drinking water are not always the same thing.
```

```text
id: exposure.cold.001
topic: exposure.cold
question: What helps most when cold wind and rain are lowering body temperature?
answers: A) Shelter, warmth, dry conditions, and rest. B) Sprinting forever. C) Dropping all food.
correct: A
feedback: Wind, rain, fatigue, and nightfall can make exposure dangerous.
```

```text
id: shelter.drainage.001
topic: shelter.drainage
question: Why avoid placing shelter in a drainage path?
answers: A) Water can pool or flow through it. B) It makes tools sharper. C) It prevents all wind.
correct: A
feedback: Stable, drained ground improves shelter reliability.
```

```text
id: injury.bleeding.001
topic: injury.bleeding
question: What should you do before heavy work while bleeding?
answers: A) Treat bleeding and rest if possible. B) Ignore it and sprint. C) Stand in smoke.
correct: A
feedback: Bleeding and exhaustion make further mistakes and injury more likely.
```

```text
id: resource.fiber.001
topic: resource.fiber
question: Why is fiber useful early?
answers: A) Binding, panels, and shelter parts. B) It replaces all water. C) It stops night.
correct: A
feedback: Fiber is a basic binding material for primitive crafting and shelter.
```

Question-bank rule: elementary questions should be short, practical, and tied to
actions the player can immediately recognize in the MVP.

## When Deeper Questions Matter

Deeper questions should not decide whether a new player can survive the first
night. They should matter when the player is trying to do better, teach others,
or enter more complex branches.

Quality improvements:

- Use deeper checks when the player wants better yield, stronger construction,
  more durable tools, safer food, better medicine, or more efficient work.

Safer work:

- Use deeper checks when incorrect assumptions could create fire spread, injury,
  sickness, structural failure, bad weather exposure, or wasted scarce supplies.

Complex crafting:

- Use deeper checks for multi-stage recipes, material substitutions, tool
  maintenance, preserved food, medicines, buildings, and later machinery.

Teaching others:

- Use deeper checks when a player or NPC attempts to teach a concept, create a
  lesson note, train family/community members, or evaluate whether someone
  understood a dangerous task.

Advanced branches:

- Use deeper checks for farming, animal care, medicine, engineering, trade,
  navigation, governance, science, and future advanced technology.

Depth rule: deeper questions should improve mastery and responsibility. They
should not be busywork for actions the character has already demonstrated
through repeated safe practice.

## Exploit And Rote-Memorization Guardrails

The learning system should reward understanding and practice, not repetitive
input farming or memorizing answer order.

Exploit farming risks:

- Repeating the same safe action for unlimited experience.
- Creating harmless failures just to farm mistake feedback.
- Spamming prompts or questions for repeated rewards.
- Using alternate accounts or group work to duplicate teaching credit.
- Performing actions with no meaningful cost, context, or outcome.

Guardrails:

- Apply diminishing returns to identical repeated actions.
- Require meaningful context for experience: time, resource cost, risk,
  environmental variation, or consequence.
- Track recent prompt/question exposure and suppress repeated rewards.
- Give recovery credit only when the player takes a useful corrective action.
- Separate "learned concept" from "perfect mastery" so one answer does not solve
  every future situation.
- Prefer concept families and varied wording over fixed answer-order memorizing.

Anti-exploit rule: rewards should come from meaningful decisions, varied
practice, and good recovery, not from low-cost repetition.

## Knowledge Persistence Requirements

Knowledge and skill state must survive save/load, server restarts, and future
character handoff systems without resetting learning progress or tutorial
fatigue.

Persisted state:

- Stable knowledge profile ID linked to the player character or NPC.
- Learned concepts by stable concept ID.
- Practical skill experience by taxonomy domain.
- Mastery/confidence tier per topic, separate from raw experience.
- Failed attempts that produced useful feedback, including cause category,
  recovery action, and recent cooldown state.
- Tutorial and contextual prompt state: seen, dismissed, repeated, snoozed, and
  next eligible display time.
- Optional knowledge checks answered, skipped, failed, or recently displayed.
- Teaching, observation, and shared-work learning events that granted credit.
- Schema version, migration marker, and source build/version for future cleanup.

Save/load rules:

- The server is authoritative for writes in multiplayer.
- Client UI may cache prompt visibility, but save data comes from validated
  server state.
- Save enough recent action and prompt history to prevent reset-based farming.
- Keep learned concepts stable across wording changes in the question bank.
- Preserve failed attempts long enough to support better feedback and avoid
  repeating the same hint every few seconds.
- Store tutorial state per character/profile, not globally across all worlds.
- Never store private credentials, personal account data, or real-world source
  notes in player save records.

Persistence rule: learning state should make a returning character feel
continuous while giving designers enough history to tune teaching, feedback, and
anti-exploit behavior.

## Multiplayer Learning Rules

Learning in multiplayer should make cooperation valuable without turning nearby
players into passive experience sources.

Teaching:

- The server validates teaching credit.
- The teacher must know the concept, have enough practical experience, or
  demonstrate the action in the current context.
- The learner must be nearby, attentive, and eligible for the concept.
- Teaching grants bounded awareness or practice credit, not instant mastery.
- Dangerous concepts require supervised practice before full confidence is
  awarded.

Observation:

- Nearby observation can unlock awareness of a concept when the action is
  visible and relevant.
- Passive observation grants less credit than direct practice.
- Repeated passive observation has diminishing returns.
- Observation does not grant credit while idle, disconnected, hidden from the
  action, or outside the relevant range.

Shared work:

- Group tasks can grant role-specific experience to active contributors.
- Roles should be explicit enough to audit later: gatherer, builder, fire
  watcher, first aid helper, scout, teacher, cook, hauler, or defender.
- Failed group work can teach useful feedback when a player helps diagnose or
  correct the problem.
- Idle proximity, item handoff spam, and repeated low-risk loops should not
  grant shared-work credit.

Group skill benefits:

- Skilled contributors can reduce risk, improve quality, increase speed, or
  make warnings more visible for the group task.
- Benefits should be capped so one expert does not remove all challenge.
- Benefits apply only while the contributor is present, equipped, and actively
  helping.
- No global aura: skill benefits do not apply across the map or while logged
  off unless a future offline-simulation rule explicitly grants protection.

Network rules:

- Client learning requests are hints only.
- Server authority validates distance, visibility, participation, role,
  cooldown, tools, environmental context, and outcome before granting credit.
- Teaching, observation, and shared-work events must be persisted for tuning and
  anti-exploit review.

Multiplayer rule: cooperation should transfer awareness, improve group outcomes,
and reward active contribution without bypassing practice, risk, or context.
