Feat/policies and docs

.github/copilot-instructions.md

@@ -269,3 +269,28 @@ Note: The helper set lives under `spec/support/automatic_test_configuration.rb`
   expect(response).to redirect_to(person_blocks_path)
   ```
 - **Factory Requirements**: Every Better Together model needs a corresponding FactoryBot factory with proper engine namespace handling
+
+### RSpec Best Practices
+- **Named subjects for explicit references**: When using `expect(subject)` with complex matchers (like `have_many`), always define a named subject in the describe block:
+  ```ruby
+  describe 'associations' do
+    subject(:model_name) { build(:factory_name) }
+
+    it { is_expected.to belong_to(:association) }
+
+    it do
+      expect(model_name).to have_many(:items)
+        .class_name('Namespace::Item')
+        .dependent(:destroy)
+    end
+  end
+  ```
+- **Pending tests require reasons**: Use `skip` inside `it` blocks with a descriptive reason instead of `xit`:
+  ```ruby
+  it 'complex feature requiring external service' do
+    skip 'External service not available in test environment'
+    # test code here
+  end
+  ```
+- **Use `is_expected.to` for simple one-line matchers**: Prefer implicit subject with `is_expected.to` for single-assertion tests
+- **Use named subject for multi-line or complex matchers**: Define `subject(:name)` when tests need explicit subject references

AGENTS.md

@@ -276,6 +276,31 @@ Note: The helper set lives under `spec/support/automatic_test_configuration.rb`
 - **Integration**: Test complete user workflows and cross-model interactions.
 - **Feature Tests**: End-to-end stakeholder workflows validating acceptance criteria.
 
+### RSpec Best Practices
+- **Named subjects for explicit references**: When using `expect(subject)` with complex matchers (like `have_many`), always define a named subject in the describe block:
+  ```ruby
+  describe 'associations' do
+    subject(:model_name) { build(:factory_name) }
+
+    it { is_expected.to belong_to(:association) }
+
+    it do
+      expect(model_name).to have_many(:items)
+        .class_name('Namespace::Item')
+        .dependent(:destroy)
+    end
+  end
+  ```
+- **Pending tests require reasons**: Use `skip` inside `it` blocks with a descriptive reason instead of `xit`:
+  ```ruby
+  it 'complex feature requiring external service' do
+    skip 'External service not available in test environment'
+    # test code here
+  end
+  ```
+- **Use `is_expected.to` for simple one-line matchers**: Prefer implicit subject with `is_expected.to` for single-assertion tests
+- **Use named subject for multi-line or complex matchers**: Define `subject(:name)` when tests need explicit subject references
+
 ## TDD Test Types by Stakeholder Need
 
 ### End User-Focused Tests

Gemfile.lock

@@ -55,6 +55,7 @@ PATH
       rack-cors (>= 1.1.1, < 3.1.0)
       rack-mini-profiler
       rails (>= 7.2, < 8.1)
+      redcarpet (~> 3.6)
       reform-rails (>= 0.2, < 0.4)
       rswag (>= 2.3.1, < 2.18.0)
       ruby-openai
@@ -609,6 +610,7 @@ GEM
       erb
       psych (>= 4.0.0)
       tsort
+    redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
     redis-client (0.26.1)

app/assets/stylesheets/better_together/content_blocks.scss

@@ -241,3 +241,197 @@
     margin-left: 5px;
   }
 }
+
+// Markdown content styling - GitHub-flavored markdown styles
+.markdown-content {
+  line-height: 1.6;
+  color: #24292e;
+
+  // Headings
+  h1, h2, h3, h4, h5, h6 {
+    margin-top: 24px;
+    margin-bottom: 16px;
+    font-weight: 600;
+    line-height: 1.25;
+    border-bottom: 1px solid #eaecef;
+    padding-bottom: 0.3em;
+  }
+
+  h1 { font-size: 2em; }
+  h2 { font-size: 1.5em; }
+  h3 { font-size: 1.25em; }
+  h4 { font-size: 1em; }
+  h5 { font-size: 0.875em; }
+  h6 { font-size: 0.85em; color: #6a737d; }
+
+  // Paragraphs and text
+  p {
+    margin-top: 0;
+    margin-bottom: 16px;
+  }
+
+  // Links
+  a {
+    color: #0366d6;
+    text-decoration: none;
+
+    &:hover {
+      text-decoration: underline;
+    }
+  }
+
+  // Lists
+  ul, ol {
+    padding-left: 2em;
+    margin-top: 0;
+    margin-bottom: 16px;
+  }
+
+  li {
+    margin-bottom: 0.25em;
+
+    > p {
+      margin-top: 16px;
+    }
+
+    + li {
+      margin-top: 0.25em;
+    }
+  }
+
+  // Blockquotes
+  blockquote {
+    padding: 0 1em;
+    color: #6a737d;
+    border-left: 0.25em solid #dfe2e5;
+    margin: 0 0 16px 0;
+
+    > :first-child {
+      margin-top: 0;
+    }
+
+    > :last-child {
+      margin-bottom: 0;
+    }
+  }
+
+  // Code blocks
+  pre {
+    padding: 16px;
+    overflow: auto;
+    font-size: 85%;
+    line-height: 1.45;
+    background-color: #f6f8fa;
+    border-radius: 6px;
+    margin-bottom: 16px;
+
+    code {
+      display: inline;
+      padding: 0;
+      margin: 0;
+      overflow: visible;
+      line-height: inherit;
+      word-wrap: normal;
+      background-color: transparent;
+      border: 0;
+    }
+  }
+
+  // Inline code
+  code {
+    padding: 0.2em 0.4em;
+    margin: 0;
+    font-size: 85%;
+    background-color: rgba(27, 31, 35, 0.05);
+    border-radius: 6px;
+    font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+  }
+
+  // Tables
+  table {
+    border-spacing: 0;
+    border-collapse: collapse;
+    margin-top: 0;
+    margin-bottom: 16px;
+    width: 100%;
+    overflow: auto;
+
+    th {
+      font-weight: 600;
+      padding: 6px 13px;
+      border: 1px solid #dfe2e5;
+      background-color: #f6f8fa;
+    }
+
+    td {
+      padding: 6px 13px;
+      border: 1px solid #dfe2e5;
+    }
+
+    tr {
+      background-color: #fff;
+      border-top: 1px solid #c6cbd1;
+
+      &:nth-child(2n) {
+        background-color: #f6f8fa;
+      }
+    }
+  }
+
+  // Horizontal rules
+  hr {
+    height: 0.25em;
+    padding: 0;
+    margin: 24px 0;
+    background-color: #e1e4e8;
+    border: 0;
+  }
+
+  // Task lists
+  .task-list-item {
+    list-style-type: none;
+
+    input {
+      margin: 0 0.2em 0.25em -1.6em;
+      vertical-align: middle;
+    }
+  }
+
+  // Images
+  img {
+    max-width: 100%;
+    box-sizing: content-box;
+    background-color: #fff;
+    border-radius: 6px;
+  }
+
+  // Strikethrough
+  del {
+    text-decoration: line-through;
+  }
+
+  // Superscript
+  sup {
+    vertical-align: super;
+    font-size: smaller;
+  }
+
+  // Highlight
+  mark {
+    background-color: #fff740;
+    padding: 0.2em;
+  }
+
+  // Footnotes
+  .footnotes {
+    margin-top: 32px;
+    padding-top: 16px;
+    border-top: 1px solid #e1e4e8;
+    font-size: 0.9em;
+    color: #6a737d;
+
+    ol {
+      padding-left: 1.5em;
+    }
+  }
+}