Docs hardening: security, quickstart cleanup, and repo guardrails

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+- What changed:
+- Why:
+
+## Related Issue
+
+- Refs #
+
+## Documentation Checklist
+
+- [ ] No real credentials, API keys, or secrets were added
+- [ ] Updated links and Markdown anchors were checked
+- [ ] API snippets were reviewed for endpoint/payload consistency
+- [ ] Security-sensitive changes were reflected in `Security.md` if needed

.github/workflows/docs-checks.yml

@@ -0,0 +1,48 @@
+name: Docs Checks
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs-checks.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.md"
+      - ".github/workflows/docs-checks.yml"
+
+jobs:
+  link-check:
+    name: Link Check (blocking)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Check markdown links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --no-progress
+            --verbose
+            --accept 200,401,429
+            '**/*.md'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  markdown-lint:
+    name: Markdown Lint (non-blocking)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Lint markdown
+        id: lint
+        continue-on-error: true
+        uses: DavidAnson/markdownlint-cli2-action@v18
+        with:
+          globs: |
+            **/*.md
+      - name: Report non-blocking lint result
+        if: steps.lint.outcome == 'failure'
+        run: echo "Markdown lint found style issues (non-blocking)."

.gitignore

@@ -0,0 +1,18 @@
+# macOS
+.DS_Store
+
+# Editors
+.idea/
+.vscode/
+*.swp
+
+# Python
+__pycache__/
+*.pyc
+
+# Node
+node_modules/
+
+# Local env files
+.env
+.env.*

AGENTS.md

@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repository is documentation-first.
+
+- `README.md`: Primary project overview, links, and community entry points.
+- `api/README.md`: API quickstart and request examples.
+- `Security.md`: Vulnerability reporting and security policy.
+- `antler_hackathon.md`: Event-specific reference material.
+- Root metadata: `LICENSE`, `CODE_OF_CONDUCT.md`, `CNAME`.
+
+Keep new content close to its audience: API usage updates belong in `api/README.md`; organization or product messaging belongs in `README.md`.
+
+## Build, Test, and Development Commands
+There is no in-repo build pipeline or automated test suite currently.
+
+- `rg -n "term" README.md api/README.md`: Find and update repeated wording quickly.
+- `git status -sb`: Check branch state before and after edits.
+- `git diff -- README.md api/README.md`: Review exactly what changed.
+- `gh pr create --draft --fill`: Open a draft PR after pushing your branch.
+
+For docs changes, treat link validity, snippet accuracy, and formatting consistency as the release gate.
+
+## Coding Style & Naming Conventions
+- Use clear Markdown headings (`##`, `###`) and short sections.
+- Prefer concise, imperative prose and concrete examples.
+- Use fenced code blocks for request snippets.
+- Use lowercase, hyphenated branch names such as `42-api-doc-refresh`.
+- Keep filenames descriptive and stable; avoid creating duplicate topic files.
+
+## Testing Guidelines
+No formal coverage target is defined for this repository.
+
+- Manually verify API snippets before merging (request path, payload keys, auth header format).
+- Confirm external links resolve and point to canonical docs.
+- If you change example inputs/outputs, ensure narrative text matches code blocks.
+
+## Commit & Pull Request Guidelines
+Recent history uses short, imperative subjects (for example, `Update README.md`, `Create CNAME`, `chore: ...`). Follow that pattern.
+
+- Commit format: `<type(optional)>: <brief imperative summary>`.
+- Keep commits scoped to one topic (README, API docs, or policy update).
+- PRs should include: purpose, changed files, linked issue (for example `Refs #42`), and any screenshots only when visual output changed.
+
+## Security & Configuration Tips
+Never commit real credentials, tokens, or private endpoints. In examples, prefer placeholders (`<username>`, `${ACCESS_TOKEN}`) and reference secure reporting flow in `Security.md`.

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for contributing to the Sublime repository.
+
+## Scope of This Repository
+
+This repository is documentation-first. Most contributions update:
+- `README.md`
+- `api/README.md`
+- `antler_hackathon.md`
+- `Security.md`
+
+## Branch and Commit Guidelines
+
+- Create a focused branch from `main`, for example: `42-docs-security-fix`.
+- Keep commits small and scoped by topic.
+- Use short, imperative commit messages:
+  - `Update API quickstart error handling`
+  - `chore: add docs CI`
+
+## Pull Request Checklist
+
+Before opening a PR:
+
+1. Confirm no real credentials, secrets, or tokens are present.
+2. Validate links and anchors in edited Markdown files.
+3. Ensure code snippets match the surrounding narrative.
+4. Link the related issue in the PR body (for example: `Refs #42`).
+
+## Review Expectations
+
+- Prefer small PRs with a clear purpose.
+- Include a brief summary of changed files and why.
+- Add screenshots only when visual output meaningfully changes.

README.md

@@ -3,28 +3,6 @@
 
 Behavior Change as a Service🌞    
 
-
-<!--[![recomment]](https://ideas.subconscious.ai/)
-
-<!--[![Release Notes](https://docs.google.com/document/d/1BVZsVeQnk9AMC1zxN3pw_LPjOKrEtBVPXmmiqTDdzVs/edit#heading=h.cok4hkezrxg)
-[![CI]()]()
-[![Downloads](https://static.pepy.tech/badge/langchain/month)](https://pepy.tech/project/langchain)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/langchainai.svg?style=social&label=Follow%20%40LangChainAI)](https://twitter.com/langchainai)
-[![](https://dcbadge.vercel.app/api/server/6adMQxSpJS?compact=true&style=flat)](https://discord.com/invite/3bgj4ZhABz)
-[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/langchain-ai/langchain)
-[![GitHub star chart](https://img.shields.io/github/stars/langchain-ai/langchain?style=social)](https://star-history.com/#Subconscious-ai/sublime/)
-[![Open Issues](https://img.shields.io/github/issues-raw/langchain-ai/langchain)](https://github.com/Subconscious-ai/sublime/issues)
-[![Slack](https://img.shields.io/badge/slack--channel-blue?logo=slack)]()
-
-[![Go Reference](https://pkg.go.dev/badge/github.com/weaviate/weaviate.svg)](https://pkg.go.dev/github.com/weaviate/weaviate)
-[![Build Status](https://github.com/weaviate/weaviate/actions/workflows/.github/workflows/pull_requests.yaml/badge.svg?branch=main)](https://github.com/weaviate/weaviate/actions/workflows/.github/workflows/pull_requests.yaml)
-[![Go Report Card](https://goreportcard.com/badge/github.com/weaviate/weaviate)](https://goreportcard.com/report/github.com/weaviate/weaviate)
-[![Coverage Status](https://codecov.io/gh/weaviate/weaviate/branch/main/graph/badge.svg)](https://codecov.io/gh/weaviate/weaviate)
-[![Slack](https://img.shields.io/badge/slack--channel-blue?logo=slack)](https://weaviate.io/slack)
-[![GitHub Tutorials](https://img.shields.io/badge/Weaviate_Tutorials-green)](https://github.com/weaviate-tutorials/) 
-[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/langchain-ai/langchain)-->
-
 [![Open Issues](https://img.shields.io/github/issues-raw/Subconscious-ai/sublime)](https://github.com/Subconscious-ai/sublime/issues) [![Release Notes](https://img.shields.io/badge/Release-Notes-blue)](https://docs.google.com/document/d/1BVZsVeQnk9AMC1zxN3pw_LPjOKrEtBVPXmmiqTDdzVs/edit#heading=h.cok4hkezrxg)
 [![Stars](https://img.shields.io/github/stars/Subconscious-ai/sublime)](https://star-history.com/#Subconscious-ai/sublime/)
 
@@ -53,17 +31,21 @@ We poll the Representative Population to obtain answers for each respondent. Eac
 ### Reporting and Expansion
 Results are analyzed using state-of-the-art causal modeling techniques. The coefficients are used to estimate the preferences of subgroups in the population, create clusters, and report on which features of the product each persona prefers, and why.
 
+## 📚 Documentation Map
+- `api/README.md`: canonical quickstart for token setup and first API workflow.
+- `antler_hackathon.md`: extended end-to-end walkthrough with deeper examples.
+- `Security.md`: vulnerability disclosure policy for this repository.
+
 ## 💬  Important Links
-- [Getting Started!](https://github.com/Subconscious-ai/sublime/blob/API/api/README.md)
-- [Demo, Get to Know Us!]()
+- [Getting Started](api/README.md)
 - [Subconscious AI Wiki](https://docs.subconscious.ai/)
 - [API Playground](https://api.subconscious.ai/docs#/)
-- [API Documentation]()
+- [Security Policy](Security.md)
 
 ## Join Us!
 Please reach out, and join our community:
 - [Linkedin](https://www.linkedin.com/company/subconscious-ai/)
-- [Twitter](https://www.linkedin.com/company/subconscious-ai/)
+- [Twitter](https://twitter.com/subconscious_ai)
 - [Discord](https://discord.com/invite/3bgj4ZhABz)
 - [Email](press@subconscious.ai)
 
@@ -73,11 +55,9 @@ Please reach out, and join our community:
  [<img src="https://github.com/AidaE.png" width="60px;"/>](https://github.com/AidaE) 
  [<img src="https://github.com/aastroza.png" width="60px;"/>](https://github.com/aastroza) 
  [<img src="https://github.com/aviyashchin.png" width="60px;"/>](https://github.com/aviyashchin)
- [<img src="https://github.com/CodeJellee.png" width="60px;"/>](https://github.com/CodeJellee) 
  [<img src="https://github.com/Darcy667.png" width="60px;"/>](https://github.com/Darcy667) 
  [<img src="https://github.com/JadeChan03.png" width="60px;"/>](https://github.com/JadeChan03) 
  [<img src="https://github.com/jessiezhang39.png" width="60px;"/>](https://github.com/jessiezhang39) 
- [<img src="https://github.com/MahdiJafari1.png" width="60px;"/>](https://github.com/MahdiJafari1) 
  [<img src="https://github.com/MahithaSann.png" width="60px;"/>](https://github.com/MahithaSann) 
  [<img src="https://github.com/mikefischer.png" width="60px;"/>](https://github.com/mikefischer) 
  [<img src="https://github.com/rbolline.png" width="60px;"/>](https://github.com/rbolline) 

Security.md

@@ -1,61 +1,33 @@
 # Security Policy
 
-## Reporting OSS Vulnerabilities
+## Reporting Vulnerabilities
 
-Subconscious is partnered with [huntr by Protect AI](https://huntr.com/) to provide 
-a bounty program for our open source projects. 
+If you discover a security issue in this repository or the examples it contains:
 
-Please report security vulnerabilities associated with the Subconscious 
-open source projects by visiting the following link:
+1. Submit a report via huntr: [https://huntr.com/bounties/disclose/](https://huntr.com/bounties/disclose/?target=https%3A%2F%2Fgithub.com%2FSubconscious-ai%2Fsublime&validSearch=true)
+2. If huntr is unavailable or your report is time-sensitive, email: `security@subconscious.ai`
 
-[https://huntr.com/bounties/disclose/](https://huntr.com/bounties/disclose/?target=https%3A%2F%2Fgithub.com%2FSubconscious-ai%2FSubconscious&validSearch=true)
+Please include:
+- A clear description of the issue and impact
+- Reproduction steps or proof of concept
+- Any affected files, links, or endpoints
 
-Before reporting a vulnerability, please review:
+Do not open public GitHub issues for unpatched security vulnerabilities.
 
-1) In-Scope Targets and Out-of-Scope Targets below.
-2) The [Subconscious-ai/Subconscious](https://python.Subconscious.com/docs/contributing/repo_structure) monorepo structure.
-3) Subconscious [security guidelines](https://python.Subconscious.com/docs/security) to
-   understand what we consider to be a security vulnerability vs. developer
-   responsibility.
+## Scope
 
-### In-Scope Targets
+This policy applies to content in this repository, including:
+- Documentation and examples in `README.md`, `api/README.md`, and `antler_hackathon.md`
+- Repository configuration and workflow files
 
-The following packages and repositories are eligible for bug bounties:
+Third-party services linked from this repository are out of scope unless the issue is caused by this repository's configuration or guidance.
 
-- Subconscious-core
-- Subconscious (see exceptions)
-- Subconscious-community (see exceptions)
-- langgraph
-- langserve
+## Secret Handling
 
-### Out of Scope Targets
+- Never commit real credentials, API keys, client secrets, or tokens.
+- Use placeholders such as `<username>`, `${SUBCONSCIOUS_TOKEN}`, and `<client_id>`.
+- If credentials are accidentally committed, rotate them immediately and submit a private security report.
 
-All out of scope targets defined by huntr as well as:
+## Responsible Disclosure
 
-- **Subconscious-experimental**: This repository is for experimental code and is not
-  eligible for bug bounties, bug reports to it will be marked as interesting or waste of
-  time and published with no bounty attached.
-- **tools**: Tools in either Subconscious or Subconscious-community are not eligible for bug
-  bounties. This includes the following directories
-  - Subconscious/tools
-  - Subconscious-community/tools
-  - Please review our [security guidelines](https://python.Subconscious.com/docs/security)
-    for more details, but generally tools interact with the real world. Developers are
-    expected to understand the security implications of their code and are responsible
-    for the security of their tools.
-- Code documented with security notices. This will be decided done on a case by
-  case basis, but likely will not be eligible for a bounty as the code is already
-  documented with guidelines for developers that should be followed for making their
-  application secure.
-- Any LangSmith related repositories or APIs see below.
-
-## Reporting LangSmith Vulnerabilities
-
-Please report security vulnerabilities associated with LangSmith by email to `security@Subconscious.dev`.
-
-- LangSmith site: https://smith.Subconscious.com
-- SDK client: https://github.com/Subconscious-ai/langsmith-sdk
-
-### Other Security Concerns
-
-For any other security concerns, please contact us at `security@Subconscious.dev`.
+We ask reporters to avoid public disclosure until the issue has been triaged and mitigated. We will acknowledge valid reports and coordinate remediation timelines.

antler_hackathon.md

@@ -1,5 +1,7 @@
 # Subconscious AI API Documentation
 
+> Note: For the canonical quickstart, use `api/README.md`. This document is an extended reference with larger payload examples.
+
 ## Welcome to Subconscious AI
 
 Subconscious AI redefines market research and product development with our innovative "Behaviour Change as a Service" model. Powered by advanced Large Language Models (LLMs), we enable businesses to conduct **Causal Market Research** with unmatched speed, quality, and ethical standards. Our platform delivers human-level reliability, guiding you through **Ideation**, **User Research**, and **Product Design**. Subconscious AI is your partner in understanding and influencing consumer behavior.
@@ -115,7 +117,7 @@ response = httpx.post(
 
 Finally, we can now run our experiment! But first, we need to setup the data to run the experiment.
 
-[//]: # (todo: the result of the previosu step should be used here to populate the attributes and levels)
+[//]: # (TODO: use the output of the previous step to populate attributes and levels.)
 
 **Purpose:** Launches a conjoint analysis experiment to measure customer preferences and understand what drives behavior change.
 
@@ -819,4 +821,4 @@ client.close()
 
 For additional support and detailed documentation, visit our resources or contact the Subconscious AI team.
 
-**Happy researching! 🚀**
+**Happy researching! 🚀**