Release v1.5.0: PURPOSE.md and local template-feedback folder

.gitignore

@@ -3,3 +3,6 @@ dist/
 tmp/
 .idea/
 *.log
+.skill-template-feedback/*
+!.skill-template-feedback/.gitkeep
+!.skill-template-feedback/README.md

.skill-template-feedback/README.md

@@ -0,0 +1,9 @@
+# Skill template feedback
+
+This folder is a local staging area for notes and artifacts about the template this skill was generated from, [TechSpokes/skill-base-template](https://github.com/TechSpokes/skill-base-template).
+
+When maintaining this skill reveals a gap in the template, for example an outdated default, a missing safeguard, or an unclear instruction, capture it here, then surface it upstream as an issue or a pull request so future generated skills inherit the fix.
+
+The contents of this folder are git-ignored on purpose. Only this `README.md` and a `.gitkeep` are tracked, so the convention travels with the repository while the working notes stay local. Nothing in this folder ships in the skill package.
+
+For example, a file named `SKILL-REPO-UPGRADE-GUIDE.md` here is a portable checklist for upgrading other template-generated skill repositories to the current baseline.

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 - No unreleased changes.
 
+## [v1.5.0]
+
+- Add `docs/PURPOSE.md`, a front-door document explaining why the skill exists and what it gives a developer, especially a newcomer, and link it from the README.
+- Add a tracked `.skill-template-feedback/` folder (with a README and `.gitkeep`) whose contents are git-ignored, as the local home for notes that should be surfaced upstream to the skill template.
+
 ## [v1.4.0]
 
 - Rewrite the README as a front page: lead with what the skill gives you in plain language, then install and use, with technical and internal detail moved to the docs.

README.md

@@ -62,6 +62,7 @@ Plain files under a `state/` folder in your repository: one navigable data file,
 
 ## Learn more
 
+- [docs/PURPOSE.md](docs/PURPOSE.md) for why this skill exists and what it gives you, especially as a new developer.
 - [docs/QUICKSTART.md](docs/QUICKSTART.md) and [docs/INSTALL.md](docs/INSTALL.md) to get started.
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/FOUNDATIONS.md](docs/FOUNDATIONS.md) to understand the design and the ideas behind it.
 - [docs/ROADMAP.md](docs/ROADMAP.md), [docs/HOW-THIS-SKILL-WAS-BUILT.md](docs/HOW-THIS-SKILL-WAS-BUILT.md), and [docs/ABOUT.md](docs/ABOUT.md) for where it is going and who builds it.

docs/PURPOSE.md

@@ -0,0 +1,33 @@
+# Purpose
+
+This document explains why the skill exists and what it gives you as a developer. If you read only two files, read this and the README.
+
+## The problem
+
+The real state of an application lives in its database: the tables and their columns, how they relate, which values are allowed, who can read and write what, and the views and functions the application exposes. Yet that truth is hard to see. It is usually spread across a large database dump and a long history of migration files, and the reasons behind the design are not written down anywhere. To answer a simple question, such as which rows a user can read, you end up reading migrations and security rules by hand and assembling the answer yourself.
+
+This is hardest for the people who most need clarity: developers new to the project, and developers who are still learning how databases work.
+
+## What it gives you
+
+A clear picture of the whole database that you can read like a document. The skill writes the current structure, the security rules, and the exposed views and functions into plain files in the repository, so you can open them, search them, and follow them without special tools.
+
+The reasons behind the design, kept next to the data. The skill encourages capturing the intent of a decision as a short comment on the database object itself, so the next person reads not only the shape of a column but why it is that shape.
+
+The ability to work without the database. Because the picture is committed to the repository, you can read and review it with no running database and no credentials. You can share a single file with a teammate or hand it to an AI assistant.
+
+Confidence that the picture is current. The files are generated from the live database and regenerated as it changes, so they reflect reality rather than someone's memory, and each change shows up as a clean diff over time.
+
+Safety while you learn. The skill only reads your database, and it asks before anything that could affect your data, so exploring is never dangerous.
+
+## If you are new
+
+When you join a project, you can understand its data layer by reading one folder instead of reverse-engineering migrations. You can ask the database questions by opening a file or searching for a name. You can see the security rules and relationships before you change anything, so you are far less likely to break something you did not understand. And when a design looks surprising, the comment next to it often tells you why, instead of leaving you to guess.
+
+## For the team
+
+The same picture captures knowledge that usually leaves when a person does, makes schema changes reviewable as diffs, and gives everyone, human or AI, the same shared understanding to reason from. Over time the repository accumulates a readable, trustworthy history of how the data layer evolved and why.
+
+## The bigger goal
+
+The aim is to make the data layer easy for both people and AI agents to work with, and safe for newcomers to operate on. The database becomes a single source of truth for its data and the intent behind its shape, readable and shareable by anyone, so that decisions about it are made with understanding rather than guesswork.

docs/releases/v1.5.0.md

@@ -0,0 +1,16 @@
+# Postgres Introspection Skill v1.5.0
+
+This release adds a purpose document for developers and a tracked home for local template feedback.
+
+## Highlights
+
+- `docs/PURPOSE.md` explains why the skill exists and what it gives you as a developer, with a section written for newcomers. It is linked from the README and sits beside it as a front-door document.
+- A tracked `.skill-template-feedback/` folder, with its own README and a `.gitkeep`, is the local home for notes about the skill template. Its contents are git-ignored, so working notes stay local while the convention travels with the repository.
+
+## Why it matters
+
+A new developer can now read one short document to understand what the skill is for and why it helps, before any technical detail. The feedback folder gives maintainers a consistent place to capture template gaps and route them upstream.
+
+## Notes
+
+Release tag: `v1.5.0`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgres-introspection",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "private": true,
   "type": "module",
   "scripts": {

packaging/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "postgres-introspection",
   "displayName": "Database Introspection",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Teaches an AI agent to build a read-only database introspection capability inside the repository it is working in, rendering live database state into committed, navigable files. Database-agnostic method with a PostgreSQL reference implementation.",
   "author": {
     "name": "TechSpokes"

packaging/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "postgres-introspection",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Teaches an AI agent to build a read-only database introspection capability inside the repository it is working in, rendering live database state into committed, navigable files. Database-agnostic method with a PostgreSQL reference implementation.",
   "author": {
     "name": "TechSpokes"